Get Job by ID

GET

getJobById

curl --request GET \
  --url https://demo.parcha.ai/api/v1/getJobById \
  --header 'Authorization: Bearer <token>'

This endpoint retrieves detailed information about a job by its ID, including its status, progress, and associated check results.

API Endpoint


GET https://api.parcha.ai/getJobById

Query Parameters

job_id

string

required

The unique identifier of the job to retrieve.

include_check_result_ids

boolean

default:"false"

If true, includes only the IDs of check results. Cannot be used with include_check_results.

include_check_results

boolean

default:"false"

If true, includes full check result objects. Cannot be used with include_check_result_ids.

include_status_messages

boolean

default:"false"

If true, includes status messages associated with the job.

Response

string

The unique identifier for the job.

agent_id

string

The ID of the agent that executed the job.

owner_id

string

The email address of the job owner.

status

string

The current status of the job (e.g., PENDING, RUNNING, COMPLETED, FAILED, RETRIED). If the status is RETRIED, it means this job instance was superseded by a new job. You should use the new_job_id to fetch the latest job information.

started_at

string

The timestamp when the job started.

completed_at

string

The timestamp when the job completed.

recommendation

string

The recommendation based on the job results.

input_payload

object

The input data provided for the job.

status_messages

array

An array of status messages associated with the job.

new_job_id

string

The unique identifier of the new job that was created as a retry of this job. This field is present only if the status is RETRIED.

original_job_id

string

The unique identifier of the original job that this job is a retry of. This field is present if this job was created as a retry of a previous job.

check_results

array

An array of check results from the job execution.

Show Check Result Example

{
  "step_description": "Tool used to determine if the business profile provided by the business matches the verified business profile",
  "name": "KYB Basic Business Profile Check",
  "instruction": "Generate and validate a basic business profile from web data and check against self attested data.",
  "command_result": {
    "agent_key": "public-bdd",
    "command_id": "kyb.basic_business_profile_check",
    "command_name": "KYB Basic Business Profile Check",
    "command_desc": "Tool used to determine if the business profile provided by the business matches the verified business profile",
    "command_instance_id": "a5494583409b41d587cd753b686bcf43",
    "output": {
      "explanation": "This task involves verifying the accuracy of self-reported business information against verified data sources. The goal is to ensure that the self-reported business profile aligns with the information verified from reliable sources.",
      "payload": {
        "type": "BasicBusinessProfileCheckResult",
        "business_name_match": {
          "exact_match": true,
          "partial_match": false,
          "source_ids": [
            "fxvqri"
          ],
          "explanation": "The business name 'Parcha' exactly matches the name found in the verified data.",
          "name": "Parcha"
        },
        "business_description_match": null,
        "business_industry_match": null
      },
      "answer": "The basic business profile check passed. The self-reported business name 'Parcha' matches the verified data, and no discrepancies were found as other fields were not provided in the self-reported data.",
      "passed": true,
      "recommendation": null,
      "alerts": {}
    },
    "agent_instance_id": "09e3133959c447b493313b1b3360cc05"
  },
  "on_check_failure": null
}

Usage Examples

curl -X GET 'https://api.parcha.ai/getJobById?job_id=123e4567-e89b-12d3-a456-426614174000&include_check_results=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
    "created_at": "2024-09-06T03:06:57.213129",
    "id": "50432480-5ab8-433c-b7be-a0e40408029a",
    "agent_id": "public-bdd",
    "descope_user_id": "U2U2iomFdkpU6FcNgU8wmEtkvnde",
    "started_at": "2024-09-06T03:06:57.645676",
    "progress": null,
    "queued_at": null,
    "tenant_id": "T2QyrSQP8m6UOfLLqTux2q0Gj5AW",
    "updated_at": "2024-09-06T03:06:57.213133",
    "celery_task_id": null,
    "owner_id": "miguel@parcha.ai",
    "status": "RETRIED",
    "new_job_id": "60532481-6bc9-444d-c8cf-b1f50509030b",
    "original_job_id": null,
    "completed_at": "2024-09-06T03:13:07.371114",
    "recommendation": "Review",
    "input_payload": {
        "id": "parcha-5f7008a3",
        "self_attested_data": {
            "type": "SelfAttestedData",
            "website": "https://parcha.ai"
        },
        "research_data": {
            "type": "WebResearchDataCheck",
            "data": {
                "type": "WebResearchData",
                "is_valid_url": false,
                "is_filtered": false
            }
        },
        "self_attested_address_check": {
            "type": "SelfAttestedAddressCheck",
            "result": {
                "type": "SelfAttestedAddressCheckResult",
                "operating_address_verified": false,
                "operating_address_is_business": false,
                "operating_address_is_pobox": false,
                "operating_address_is_residential": false
            }
        },
        "web_presence_check": {
            "type": "WebPresenceCheck",
            "data": {
                "type": "WebPresenceCheckData",
                "only_used_search_results": false,
                "only_used_self_attested_websites": false,
                "only_used_extended_search_results": false
            }
        },
        "mcc_code_check": {
            "type": "MCCCodeCheck",
            "result": {
                "type": "MCCCodeCheckResult",
                "mcc_code_description": "No description found."
            }
        }
    },
    "status_messages": [],
    "check_results": [
        {
            "job_id": "50432480-5ab8-433c-b7be-a0e40408029a",
            "command_desc": "Tool to determine if the web presence data loader succeeded.",
            "step_number": null,
            "updated_at": "2024-09-06T03:08:57.865904",
            "result_type": "CommandResult",
            "status": "complete",
            "created_at": "2024-09-06T03:06:58.149768",
            "input_data": {
                "business_name": "Parcha",
                "business_description": null
            },
            "verification_data": {
                "type": "WebPresenceCheckData",
                "self_attested_webpages": [
                    // ... (webpage data omitted for brevity)
                ]
            },
            // ... (other check results omitted for brevity)
        }
    ]
}

Notes

The include_check_result_ids and include_check_results parameters are mutually exclusive. Using both will result in a 400 Bad Request error.

Access to job details is restricted. The API will return a 401 Unauthorized error if the user doesn’t have access to the specified agent.

If the job is not found, a 404 Not Found error will be returned.

This endpoint provides a comprehensive view of a job’s status and results, allowing for detailed tracking and analysis of the KYB/KYC process.

Error Responses

400 Bad Request

object

error

string

“Cannot include both check result ids and check results in the response”

401 Unauthorized

object

error

string

“Unauthorized”

404 Not Found

object

error

string

“Job not found”

Authorizations

Authorization

string

header

required

JWT token obtained from the authentication endpoint

Query Parameters

job_id

string

required

include_check_result_ids

boolean

include_check_results

boolean

include_status_messages

boolean

Response

200

Job retrieved successfully

curl --request GET \
  --url https://demo.parcha.ai/api/v1/getJobById \
  --header 'Authorization: Bearer <token>'

GET

getJobById

curl --request GET \
  --url https://demo.parcha.ai/api/v1/getJobById \
  --header 'Authorization: Bearer <token>'

This endpoint retrieves detailed information about a job by its ID, including its status, progress, and associated check results.

API Endpoint


GET https://api.parcha.ai/getJobById

Query Parameters

job_id

string

required

The unique identifier of the job to retrieve.

include_check_result_ids

boolean

default:"false"

If true, includes only the IDs of check results. Cannot be used with include_check_results.

include_check_results

boolean

default:"false"

If true, includes full check result objects. Cannot be used with include_check_result_ids.

include_status_messages

boolean

default:"false"

If true, includes status messages associated with the job.

Response

string

The unique identifier for the job.

agent_id

string

The ID of the agent that executed the job.

owner_id

string

The email address of the job owner.

status

string

started_at

string

The timestamp when the job started.

completed_at

string

The timestamp when the job completed.

recommendation

string

The recommendation based on the job results.

input_payload

object

The input data provided for the job.

status_messages

array

An array of status messages associated with the job.

new_job_id

string

The unique identifier of the new job that was created as a retry of this job. This field is present only if the status is RETRIED.

original_job_id

string

The unique identifier of the original job that this job is a retry of. This field is present if this job was created as a retry of a previous job.

check_results

array

An array of check results from the job execution.

Show Check Result Example

{
  "step_description": "Tool used to determine if the business profile provided by the business matches the verified business profile",
  "name": "KYB Basic Business Profile Check",
  "instruction": "Generate and validate a basic business profile from web data and check against self attested data.",
  "command_result": {
    "agent_key": "public-bdd",
    "command_id": "kyb.basic_business_profile_check",
    "command_name": "KYB Basic Business Profile Check",
    "command_desc": "Tool used to determine if the business profile provided by the business matches the verified business profile",
    "command_instance_id": "a5494583409b41d587cd753b686bcf43",
    "output": {
      "explanation": "This task involves verifying the accuracy of self-reported business information against verified data sources. The goal is to ensure that the self-reported business profile aligns with the information verified from reliable sources.",
      "payload": {
        "type": "BasicBusinessProfileCheckResult",
        "business_name_match": {
          "exact_match": true,
          "partial_match": false,
          "source_ids": [
            "fxvqri"
          ],
          "explanation": "The business name 'Parcha' exactly matches the name found in the verified data.",
          "name": "Parcha"
        },
        "business_description_match": null,
        "business_industry_match": null
      },
      "answer": "The basic business profile check passed. The self-reported business name 'Parcha' matches the verified data, and no discrepancies were found as other fields were not provided in the self-reported data.",
      "passed": true,
      "recommendation": null,
      "alerts": {}
    },
    "agent_instance_id": "09e3133959c447b493313b1b3360cc05"
  },
  "on_check_failure": null
}

Usage Examples

curl -X GET 'https://api.parcha.ai/getJobById?job_id=123e4567-e89b-12d3-a456-426614174000&include_check_results=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
    "created_at": "2024-09-06T03:06:57.213129",
    "id": "50432480-5ab8-433c-b7be-a0e40408029a",
    "agent_id": "public-bdd",
    "descope_user_id": "U2U2iomFdkpU6FcNgU8wmEtkvnde",
    "started_at": "2024-09-06T03:06:57.645676",
    "progress": null,
    "queued_at": null,
    "tenant_id": "T2QyrSQP8m6UOfLLqTux2q0Gj5AW",
    "updated_at": "2024-09-06T03:06:57.213133",
    "celery_task_id": null,
    "owner_id": "miguel@parcha.ai",
    "status": "RETRIED",
    "new_job_id": "60532481-6bc9-444d-c8cf-b1f50509030b",
    "original_job_id": null,
    "completed_at": "2024-09-06T03:13:07.371114",
    "recommendation": "Review",
    "input_payload": {
        "id": "parcha-5f7008a3",
        "self_attested_data": {
            "type": "SelfAttestedData",
            "website": "https://parcha.ai"
        },
        "research_data": {
            "type": "WebResearchDataCheck",
            "data": {
                "type": "WebResearchData",
                "is_valid_url": false,
                "is_filtered": false
            }
        },
        "self_attested_address_check": {
            "type": "SelfAttestedAddressCheck",
            "result": {
                "type": "SelfAttestedAddressCheckResult",
                "operating_address_verified": false,
                "operating_address_is_business": false,
                "operating_address_is_pobox": false,
                "operating_address_is_residential": false
            }
        },
        "web_presence_check": {
            "type": "WebPresenceCheck",
            "data": {
                "type": "WebPresenceCheckData",
                "only_used_search_results": false,
                "only_used_self_attested_websites": false,
                "only_used_extended_search_results": false
            }
        },
        "mcc_code_check": {
            "type": "MCCCodeCheck",
            "result": {
                "type": "MCCCodeCheckResult",
                "mcc_code_description": "No description found."
            }
        }
    },
    "status_messages": [],
    "check_results": [
        {
            "job_id": "50432480-5ab8-433c-b7be-a0e40408029a",
            "command_desc": "Tool to determine if the web presence data loader succeeded.",
            "step_number": null,
            "updated_at": "2024-09-06T03:08:57.865904",
            "result_type": "CommandResult",
            "status": "complete",
            "created_at": "2024-09-06T03:06:58.149768",
            "input_data": {
                "business_name": "Parcha",
                "business_description": null
            },
            "verification_data": {
                "type": "WebPresenceCheckData",
                "self_attested_webpages": [
                    // ... (webpage data omitted for brevity)
                ]
            },
            // ... (other check results omitted for brevity)
        }
    ]
}

Notes

The include_check_result_ids and include_check_results parameters are mutually exclusive. Using both will result in a 400 Bad Request error.

Access to job details is restricted. The API will return a 401 Unauthorized error if the user doesn’t have access to the specified agent.

If the job is not found, a 404 Not Found error will be returned.

This endpoint provides a comprehensive view of a job’s status and results, allowing for detailed tracking and analysis of the KYB/KYC process.

Error Responses

400 Bad Request

object

error

string

“Cannot include both check result ids and check results in the response”

401 Unauthorized

object

error

string

“Unauthorized”

404 Not Found

object

error

string

“Job not found”

Authorizations

Authorization

string

header

required

JWT token obtained from the authentication endpoint

Query Parameters

job_id

string

required

include_check_result_ids

boolean

include_check_results

boolean

include_status_messages

boolean

Response

200

Job retrieved successfully

curl --request GET \
  --url https://demo.parcha.ai/api/v1/getJobById \
  --header 'Authorization: Bearer <token>'

API Endpoint

Query Parameters

Response

Usage Examples

Example Response

Notes

Error Responses

Authorizations

Query Parameters

Response

Getting Started

Checks Results

API Reference

Get Job by ID

API Endpoint

Query Parameters

Response

Usage Examples

Example Response

Notes

Error Responses

Authorizations

Query Parameters

Response

​API Endpoint

​Query Parameters

​Response

​Usage Examples

​Example Response

​Notes

​Error Responses

Authorizations

Query Parameters

Response

Getting Started

Checks Results

API Reference

​API Endpoint

​Query Parameters

​Response

​Usage Examples

​Example Response

​Notes

​Error Responses

Authorizations

Query Parameters

Response

API Endpoint

Query Parameters

Response

Usage Examples

Example Response

Notes

Error Responses

API Endpoint

Query Parameters

Response

Usage Examples

Example Response

Notes

Error Responses