API Request

Submit a Job

Submit a POST request to create a bulk screening job. The API accepts the job immediately and returns a 202 Accepted response containing the job id. Processing happens asynchronously in the background.

Each request must include authentication and the list of cases to screen. You can optionally specify which sanction lists to screen against, a webhook URL for completion notifications, and a display name for the job.

Idempotency

The Jobs API supports idempotent submissions via the Idempotency-Key request header. Providing a key ensures that retrying a failed or timed-out request does not create duplicate jobs.

If a job already exists for a given Idempotency-Key, the original job is returned rather than a new job being created. The apiKey used in the retry must match the one used in the original submission.

A UUID v4 string is recommended as the idempotency key value.

Idempotency-Key is not required but strongly recommended. Without it, network failures or timeouts may result in duplicate jobs counting against your monthly account limit.

Endpoint


POST https://api.ofac-api.com/v4/jobs

Required Content Type Header
A Content-Type header of application/json is required. Learn more about Content-Type Headers .

Idempotency-Key Header
Pass a Idempotency-Key header with a UUID v4 value to enable idempotent job submission. Retrying with the same key returns the original job instead of creating a new one.

Request Object

Parameters

apiKey string REQUIRED
Your unique API key.
Note This may also be passed via apiKey header.

cases array of Case objects REQUIRED
The cases to screen. Each case represents a person, entity, vessel, aircraft, or other target to be checked against sanctions lists.
Maximum of 100,000 cases per job.

Case Object

case.name string REQUIRED
Full name of the entity being screened.

case.id string RECOMMENDED
A unique ID used to map results back to this case in the job report. This is especially useful for large batch jobs.

If provided, the id is included in the result, allowing the result to be mapped back to the originating case.
If id is not provided, mapping must be done via the name field, which may be problematic if a name contains characters that were formatted by the API.

case.type enum
The type of entity.
Possible values: person, organization, vessel, aircraft.
Note Providing this field enables enhanced matching logic but does not restrict which entity types can be matched. Use the top-level types parameter to filter by type.

case.dob date
Date of birth.
Format: YYYY-MM-DD

case.gender string
Gender.
Possible values: m, f, male, female

case.citizenship string
Citizenship

case.nationality string
Nationality

case.phoneNumber string
Phone number

case.emailAddress string
Email address

case.cryptoId string
Crypto wallet ID

case.address Address

Address Object

address.address1 string
address.address2 string
address.city string
address.stateOrProvince string
address.postalCode string
address.country string

case.identification array of Identification objects
An Identification can represent any form of ID — passport, tax ID (TIN), drivers license, military ID, etc.
Note Matching is based on idNumber and country. The type field provides additional context only.

Identification Object

idNumber string
type string
country string

sources string array
Specifies which sanction lists to screen against, as an array of list ID codes.
See Data Sources for all available lists and their codes.
If omitted, all configured sources are used.
Example: ["SDN", "EU"] screens against the OFAC SDN and EU Financial Sanctions lists.

types string array
Entity type filter. Only these entity types will be evaluated during screening.
Possible values: person, organization, vessel, aircraft.

webhookUrl string
An HTTPS URL that will receive a POST notification when the job completes (JOB_COMPLETED) or fails (JOB_FAILED). See the Webhooks section for payload details.

HTTPS Required
The webhookUrl must use https://. Submitting an HTTP URL will return a 400 Bad Request with error code 4005 and the job will not be created.

jobName string
An optional display name for the job. Useful for identifying jobs in the job list.

Request JSON


{
    "apiKey": "your-api-key",
    "jobName": "string",
    "webhookUrl": "https://your-server.com/webhook",
    "sources": [
        "SDN", "NONSDN", "EU"
    ],
    "types": [
        "person", "organization", "vessel", "aircraft"
    ],
    "cases": [
        {
            "id": "string",
            "name": "string",
            "type": "string",
            "dob": "YYYY-MM-DD",
            "gender": "string",
            "citizenship": "string",
            "nationality": "string",
            "phoneNumber": "string",
            "emailAddress": "string",
            "cryptoId": "string",
            "address": {
                "address1": "string",
                "address2": "string",
                "city": "string",
                "stateOrProvince": "string",
                "postalCode": "string",
                "country": "string"
            },
            "identification": [
                {
                    "type": "string",
                    "idNumber": "string",
                    "country": "string"
                }
            ]
        }
    ]
}

List Jobs

Retrieve a list of jobs associated with your API key, ordered by submission time (newest first).

Parameters

apiKey string REQUIRED
Your unique API key. Passed as a request header.

limit integer
Maximum number of jobs to return.
Default: 10. Maximum: 100.

Endpoint


GET https://api.ofac-api.com/v4/jobs

Example


GET https://api.ofac-api.com/v4/jobs?limit=25

Get Job Status

Retrieve the current status of a job by its id. Use this endpoint to poll for job completion.

When a job reaches COMPLETED status, the response will include a reportUrl — a secure, presigned URL to download the full results. This URL expires 24 hours after the request is made, so download the report promptly or re-request the job to generate a fresh link.

Parameters

apiKey string REQUIRED
Your unique API key. Passed as a request header. Must match the API key used to create the job.

id string (UUID) REQUIRED
The job ID returned when the job was submitted. Passed as a path parameter.

Endpoint


GET https://api.ofac-api.com/v4/jobs/{id}

Example


GET https://api.ofac-api.com/v4/jobs/3fa85f64-5717-4562-b3fc-2c963f66afa6

Report URL Expiry
The reportUrl in the response is valid for 24 hours from the time of the request. After expiry, make another GET /v4/jobs/{id} request to receive a fresh download link.