API Documentation

Everything you need to integrate Credo into your application.

Base URL: https://api.credoscreening.com/api/v1Need an API key? Create a free account

Authentication

All requests require an API key passed in the x-api-key header.

curl -H "x-api-key: YOUR_API_KEY" \
     https://api.credoscreening.com/api/v1/screenings

Your API key is available on your dashboard after registration.

POST/api/v1/screenings

Screen a person against 1.2M+ entities from OFAC, sanctions, PEP, and 80+ watchlists. Returns results instantly.

Request Body

Field	Type	Required	Description
`firstName`	string	Yes	First name of the person to screen
`lastName`	string	Yes	Last name of the person to screen
`dateOfBirth`	string	No	Date of birth (YYYY-MM-DD). Improves match accuracy
`nationality`	string	No	ISO 3166-1 alpha-2 country code (e.g., US, CA, GB)
`address`	string	No	Full address for additional matching context
`idNumber`	string	No	Passport or national ID number
`externalRef`	string	No	Your reference ID. Returned in webhooks as referenceId

Example Request

curl -X POST https://api.credoscreening.com/api/v1/screenings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "firstName": "Vladimir",
    "lastName": "Putin",
    "nationality": "RU"
  }'

Response — No Match

{
  "screeningId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "hasMatch": false,
  "provider": "TRUSTCREDO",
  "queriedName": "John Smith",
  "totalMatches": 0,
  "matchedLists": [],
  "referenceId": null,
  "externalRef": null
}

Response — Match Found

{
  "screeningId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "hasMatch": true,
  "provider": "TRUSTCREDO",
  "queriedName": "Vladimir Putin",
  "totalMatches": 12,
  "matchedLists": [
    {
      "name": "OpenSanctions Default (All)",
      "listType": "sanction",
      "countryCode": "INTL",
      "entities": [
        {
          "name": "Vladimir Vladimirovich PUTIN",
          "score": 0.95,
          "matchLevel": "EXACT"
        },
        {
          "name": "Vladimir PUTIN",
          "score": 0.92,
          "matchLevel": "STRONG"
        }
      ],
      "matchTypes": ["exact", "strong"]
    }
  ],
  "referenceId": "your-external-ref",
  "externalRef": "your-external-ref"
}

GET/api/v1/screenings/:id

Retrieve a previously completed screening result by its ID.

curl https://api.credoscreening.com/api/v1/screenings/a1b2c3d4-... \
  -H "x-api-key: YOUR_API_KEY"

Match Levels

Each matched entity includes a score (0.0 to 1.0) and a matchLevel classification.

EXACT0.95 - 1.0

Near-identical name match. High confidence.

STRONG0.85 - 0.94

Strong match with minor variations (spelling, transliteration).

PARTIAL0.70 - 0.84

Partial match. Manual review recommended.

WEAK0.50 - 0.69

Low confidence. Likely a different person.

List Types

OFAC

US Treasury OFAC sanctions — SDN, Consolidated, SSI, and FSE lists.

SANCTION

Global sanctions — EU, UN, UK OFSI, Australia, Canada, Switzerland, Japan, Singapore, and more.

PEP

Politically Exposed Persons — heads of state, parliament members, senior government officials worldwide.

Webhooks

Configure a webhook URL to receive screening results asynchronously. Contact us to set up your webhook endpoint.

Event Types

screening.completedScreening finished — no watchlist matches found

screening.matchedScreening finished — one or more watchlist matches found

Webhook Payload

{
  "event": "screening.matched",
  "screeningId": "a1b2c3d4-...",
  "data": {
    "hasMatch": true,
    "provider": "TRUSTCREDO",
    "referenceId": "your-external-ref",
    "queriedName": "Vladimir Putin",
    "totalMatches": 12,
    "matchedLists": [...]
  },
  "timestamp": "2026-04-15T10:00:00.000Z"
}

Signature Verification

All webhook payloads are signed with HMAC-SHA256. Verify using these headers:

X-Webhook-SignatureHMAC-SHA256 signature of timestamp + payload

X-Webhook-TimestampUnix timestamp of when the webhook was sent

X-Webhook-IDUnique ID for this webhook delivery

Error Codes

Status	Meaning	Action
`200`	Success	Parse the response body
`400`	Bad request	Check required fields (firstName, lastName)
`401`	Unauthorized	Check your x-api-key header
`429`	Rate limit / quota exceeded	Wait or upgrade your plan
`500`	Server error	Retry with exponential backoff

Rate Limits & Quotas

Plan	Screenings/month	Rate limit
Starter	Pay per use	5,000 req/15min
Professional	Pay per use	5,000 req/15min
Corporate	Unlimited	Custom

Ready to integrate?

Create a free account and get your API key in 30 seconds.

Get API Key