API Response

Job Object

All three Jobs API endpoints return a Job object (or an array of Job objects for the list endpoint). The Job object describes the current state of a bulk screening job, including its progress, status, and — once complete — a link to download the results.

Attributes

id string (UUID)
The unique identifier for the job. Use this value to poll job status via GET /v4/jobs/{id}.

jobName string
The optional display name provided when the job was submitted.

status enum
The current state of the job. See Job Status Values below.

totalCases integer
The total number of cases submitted in this job.

processedCases integer
The number of cases screened so far. Updated periodically during processing. Use this alongside totalCases to track progress.

startTime date-time
UTC timestamp of when the job was submitted.
Format: YYYY-MM-DDTHH:mm:ss

endTime date-time
UTC timestamp of when the job completed or failed. null while the job is still running.
Format: YYYY-MM-DDTHH:mm:ss

reportUrl string
A presigned URL to download the job results as a JSON file. Only present when status is COMPLETED.

Link Expiry
Expires 24 hours after the request is made. Make a new GET /v4/jobs/{id} request to obtain a fresh link.

webhookUrl string
The webhook URL provided at submission, if any.

webhookStatus enum
The current delivery status of the webhook notification. Only present if a webhookUrl was provided at submission. See Webhook Status Values below.

webhookDeliveredAt date-time
UTC timestamp of when the webhook was successfully delivered. null until delivery succeeds.
Format: YYYY-MM-DDTHH:mm:ss

webhookLastStatusCode integer
The HTTP status code returned by the most recent webhook delivery attempt. null until at least one attempt has been made.

idempotencyKey string
The Idempotency-Key value provided at submission, if any.

errorCode integer
A numeric error code if the job failed. See Error Codes below.

errorMessage string
A human-readable description of the error if the job failed.

Job Object


{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "jobName": "string",
    "status": "COMPLETED",
    "totalCases": 5000,
    "processedCases": 5000,
    "startTime": "2024-01-15T10:30:00",
    "endTime": "2024-01-15T10:35:12",
    "reportUrl": "https://...",
    "webhookUrl": "https://your-server.com/webhook",
    "webhookStatus": "DELIVERED",
    "webhookDeliveredAt": "2024-01-15T10:35:15",
    "webhookLastStatusCode": 200,
    "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "errorCode": null,
    "errorMessage": null
}

Job Status Values

The status field reflects the current lifecycle state of a job.

Status	Description
`STARTING`	Job has been accepted and is queued for processing.
`STARTED`	Job is actively processing cases.
`COMPLETED`	Job finished successfully. `reportUrl` is available.
`STOPPING`	Job has been requested to stop and is waiting for the current batch to finish.
`STOPPED`	Job was stopped before completing.
`FAILED`	Job encountered an error during processing. See `errorCode` and `errorMessage`.
`ABANDONED`	Job entered an unrecoverable state.
`REJECTED`	Job was rejected before processing began.
`UNKNOWN`	Job state is uncertain.

Polling Recommendation
Poll GET /v4/jobs/{id} every 30-60 seconds seconds depending on job size. For very large jobs (50,000+ cases), processing may take several minutes. Use processedCases and totalCases to estimate remaining time.

In-Progress Job


{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "STARTED",
    "totalCases": 10000,
    "processedCases": 3000,
    "startTime": "2024-01-15T10:30:00",
    "endTime": null,
    "reportUrl": null,
    "errorCode": null,
    "errorMessage": null
}

Job Report

When a job reaches COMPLETED status, the reportUrl field contains a presigned download link for the results. The report is a JSON file containing only the cases where one or more sanctions matches were found — cases with no matches are omitted to minimize file size.

The report is structured as a JobReport object.

Attributes

jobId string (UUID)
The ID of the completed job.

jobName string
The display name of the job, if one was provided.

startTime date-time
UTC timestamp of when the job started.
Format: YYYY-MM-DDTHH:mm:ss

endTime date-time
UTC timestamp of when the job completed.
Format: YYYY-MM-DDTHH:mm:ss

totalCases integer
Total number of cases that were screened.

sources string array
The sanction list ID codes that were screened against.

results array of ScreenResult objects
Matches found across all screened cases. Each result corresponds to a case that had at least one match. The structure of each ScreenResult matches the match objects returned by the Sanctions Screening API.

Report URL Expiry
The reportUrl expires 24 hours after it is returned in a GET /v4/jobs/{id} response. If the link expires, make another GET /v4/jobs/{id} request to receive a fresh URL. The underlying report data is retained.

Job Report


{
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "jobName": "string",
    "startTime": "2024-01-15T10:30:00",
    "endTime": "2024-01-15T10:35:12",
    "totalCases": 5000,
    "sources": ["SDN", "NONSDN", "EU"],
    "results": [
        {
            "id": "case-001",
            "name": "Abu Abbas",
            "matchCount": 1,
            "matches": [
                {
                    "score": 100,
                    "matchSummary": {
                        "matchFields": [
                            {
                                "similarity": "EXACT",
                                "fieldName": "name",
                                "caseField": "Abu Abbas",
                                "sanctionField": "Abu Abbas",
                                "sanctionFieldNote": ""
                            }
                        ]
                    },
                    "sanction": {
                        "id": "string",
                        "type": "person",
                        "name": "Abu Abbas",
                        "source": "SDN"
                    }
                }
            ]
        }
    ]
}

Webhooks

If a webhookUrl is provided when submitting a job, the Jobs API will send an HTTPS POST request to that URL when the job completes or fails.

The webhook payload is a compact notification object — it contains identifying information about the job but not the full job state. Use the jobId to call GET /v4/jobs/{id} if you need full details or the reportUrl.

Payload Fields

version string
The payload schema version. Currently "1".

deliveryId string (UUID)
A unique identifier for this specific delivery attempt. Useful for deduplicating retries.

event enum
The event type.
Possible values: JOB_COMPLETED, JOB_FAILED

jobId string (UUID)
The ID of the job that triggered this notification.

jobName string
The display name of the job, if one was provided.

timestamp date-time
UTC timestamp of when the notification was sent.
Format: YYYY-MM-DDTHH:mm:ss

JOB_COMPLETED Payload


{
    "version": "1",
    "deliveryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event": "JOB_COMPLETED",
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "jobName": "Monthly Customer Review",
    "timestamp": "2024-01-15T10:35:15"
}

JOB_FAILED Payload


{
    "version": "1",
    "deliveryId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "event": "JOB_FAILED",
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "jobName": "Monthly Customer Review",
    "timestamp": "2024-01-15T10:35:15"
}

Webhook Status Values

The webhookStatus field on the Job object tracks the delivery lifecycle of the webhook notification from job submission through final delivery.

Status	Description
`PENDING`	The job is still processing. The webhook has not been sent yet.
`DELIVERED`	The webhook was delivered successfully (endpoint returned HTTPS 2xx).
`FAILED`	All delivery attempts were exhausted without a 2xx response.
`BLOCKED`	The webhook was blocked for security reasons.

Retries
Failed webhook deliveries are retried automatically. A webhookStatus of FAILED means all retry attempts were exhausted.

Delivered Webhook


{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "COMPLETED",
    "webhookUrl": "https://your-server.com/webhook",
    "webhookStatus": "DELIVERED",
    "webhookDeliveredAt": "2024-01-15T10:35:15",
    "webhookLastStatusCode": 200
}

Failed Webhook


{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "COMPLETED",
    "webhookUrl": "https://your-server.com/webhook",
    "webhookStatus": "FAILED",
    "webhookDeliveredAt": null,
    "webhookLastStatusCode": 503
}

Error Codes

When a job fails, the status will be FAILED and the errorCode and errorMessage fields will be populated.

Code	Name	Description
`4001`	`FILE_STORAGE_ERROR`	File storage access denied. The system was unable to access storage when saving results.
`4002`	`WEBHOOK_DELIVERY_FAILED`	The job completed but all webhook delivery attempts were exhausted without a successful response. The job itself is not affected.
`4003`	`JOB_RUNNER_ERROR`	Error invoking job runner. The job failed to start.
`4004`	`JOB_PROCESSING_ERROR`	A general error occurred during case processing.
`4005`	`WEBHOOK_URL_INVALID`	The `webhookUrl` provided is not a valid HTTPS URL. The job was not created. Returned as a `400 Bad Request` at submission time.

Failed Job


{
    "id": string,
    "status": ENUM, 
    "totalCases": int,
    "processedCases": int,
    "startTime": "YYYY-MM-DDTHH:mm:ss",
    "endTime": "YYYY-MM-DDTHH:mm:ss",
    "reportUrl": url,
    "errorCode": int,
    "errorMessage": string
}

HTTP Status Codes

The API returns the following HTTP status codes.

Code	Status	Description
202	Accepted	Job was successfully created and queued for processing.
200	OK	Request succeeded (used for GET requests and idempotent re-submissions).
400	Bad Request	The request was invalid. Returned for missing case names, invalid `webhookUrl` values (error code `4005`), etc.
401	Unauthorized	Invalid or missing API key, or API key does not match the job owner.
404	Not Found	No job found for the given `id`.
500	Internal Server Error	A server error occurred and the request could not be processed.