Get Job by ID - Parcha API Documentation

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/api/v1/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.

jsonpath_query

string

Optional JSONPath query to filter and extract specific fields from the response. Useful for reducing payload size when include_check_results=true returns large amounts of data. See Filtering Check Results below for examples.

Filtering Check Results

When using include_check_results=true, the response can contain large amounts of data. Use the jsonpath_query parameter to filter and extract only the data you need.

JSONPath Syntax

The API uses JSONPath syntax for filtering. Here are common patterns:

Filter by field value: $.check_results[?(@.field=='value')]
Get all items: $.check_results[*]
Extract specific field: $.check_results[*].field_name
Nested field access: $.check_results[*].payload.nested_field

Common Use Cases

Filter by specific check (command_id)

Get only the results for a specific check type:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.web_presence_check")]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array containing only the web presence check result

Get only failed checks

Filter to see only checks that didn’t pass:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.passed==false)]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of failed check results

Extract specific payload fields

Get just the payload type from all check results:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[*].payload.type' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of payload type strings (e.g., ["WebPresenceCheckResult", "PolicyCheckResult"])

Get nested array data

Extract specific nested fields from check result payloads:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.web_presence_check")].payload.verified_hits[*].hit_name' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of hit names from the verified_hits array (e.g., ["LinkedIn", "Crunchbase"])

Filter by check status

Get all completed checks:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.status=="complete")]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of completed check results

Adverse Media Filtering Examples

For detailed adverse media structure, see the Adverse Media Screening Check documentation.

Get all adverse media articles

Retrieve all verified adverse media hits for a job:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of all adverse media profiles found

Get only articles where business is the perpetrator

Filter for articles where the business is identified as the perpetrator:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.is_perpetrator==true)]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of weblinks where is_perpetrator is true

Get articles from specific sources

Filter for articles from Google Search only:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.article_source=="serp_google_search")]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of weblinks from Google SearchOther sources: refinitiv_world_check, comply_advantage, serp_google_news, serp_brave_search

Get articles about specific topics

Filter for articles about regulatory violations:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?("Regulatory Violations" in @.metadata.topics)]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of weblinks with “Regulatory Violations” in topicsCommon topics: “Legal Disputes”, “Compliance Issues”, “Safety Issues”, “Financial Misconduct”, “Criminal Activity”

Get article titles and URLs only

Extract just the article titles and URLs:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[*][title,url]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of objects with only title and url fields

Get articles from recent years

Filter for articles published in 2024 or later:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.year_of_article_publication>=2024)]' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of weblinks published in 2024 or later

Get article summaries by country

Get summaries for articles from a specific country:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?("United States" in @.where_countries)].metadata.summary_of_event' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of event summaries for articles from the United States

Get direct quotes from articles

Extract all direct quotes about the business:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[*].metadata.quote_from_article' \
-H 'Authorization: Bearer YOUR_API_KEY'

Returns: Array of direct quotes from adverse media articles

Python Example

import requests
from urllib.parse import quote

api_key = 'YOUR_API_KEY'
job_id = '123e4567-e89b-12d3-a456-426614174000'

# Filter for failed checks
jsonpath_query = '$.check_results[?(@.passed==false)]'
url = f'https://api.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true&jsonpath_query={quote(jsonpath_query)}'

headers = {'Authorization': f'Bearer {api_key}'}
response = requests.get(url, headers=headers)

# Response contains only failed checks
failed_checks = response.json()
print(f"Found {len(failed_checks)} failed checks")

Error Handling

400 Bad Request

object

Returned when the JSONPath query has invalid syntax.

Show Example Error

{
  "error": "Invalid JSONPath query: Error on line 1, col 16: Unexpected character: ?"
}

404 Not Found

object

Returned when the JSONPath query returns no results.

Show Example Error

{
  "error": "JSONPath query returned no results"
}

JSONPath Resources:

JSONPath Online Evaluator - Test your queries
JSONPath Documentation - Full syntax reference
The API uses the jsonpath-ng library with extended filter support

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": "your-kyb-agent-key",
    "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/api/v1/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": "your-agent-key",
    "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

API key obtained from your Parcha account settings. Include as Bearer token in the Authorization header.

Query Parameters

job_id

string

required

include_check_result_ids

boolean

include_check_results

boolean

include_status_messages

boolean

Response

Job retrieved successfully

​API Endpoint

​Query Parameters

​Filtering Check Results

​JSONPath Syntax

​Common Use Cases

​Adverse Media Filtering Examples

​Python Example

​Error Handling

​Response

​Usage Examples

​Example Response

​Notes

​Error Responses

Authorizations

Query Parameters

Response

API Endpoint

Query Parameters

Filtering Check Results

JSONPath Syntax

Common Use Cases

Adverse Media Filtering Examples

Python Example

Error Handling

Response

Usage Examples

Example Response

Notes

Error Responses