Verifying a Counterparty

Overview

Verify a counterparty using the POST /api/identity_verifications endpoint. Counterparty verification screens the counterparty's personally identifiable information (PII) through watchlist checks against government sanctions lists, politically exposed persons (PEP) databases, and adverse media sources.

This verification works for both individual and business counterparties. It is a simple API call that does not require initializing any SDK.

Prerequisites

Before verifying a counterparty, ensure that

Counterparty exists - The counterparty must be created via POST /api/counterparties
Counterparty type - The counterparty can be either individual or business type
PII data present - The counterparty must have the required PII for screening
Counterparty state - The counterparty must be in unverified state

Creating a Verification

To create a counterparty identity verification, send a POST request to /api/identity_verifications

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "{counterparty_guid}"
}

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `counterparty`
`method`	string	Yes	Must be `watchlists`
`counterparty_guid`	string	Yes	The GUID of the counterparty you wish to verify

Optional Parameters (Sandbox Only)

Parameter	Type	Description
`expected_behaviours`	array	Simulate specific outcomes in sandbox. Values: `passed_immediately`, `failed_immediately`

ℹ️
Sandbox Testing
The expected_behaviours parameter is only available in sandbox environments and is rejected in production.

Sandbox Example:

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "{counterparty_guid}",
  "expected_behaviours": ["passed_immediately"]
}

Response

Creating a counterparty identity verification returns an identity verification object

{
  "guid": "{identity_verification_guid}",
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "{counterparty_guid}",
  "customer_guid": "{customer_guid}",
  "state": "storing",
  "outcome": null,
  "failure_codes": [],
  "compliance_decisions": [],
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Verification States

After creating a counterparty identity verification, it progresses through the following states

storing ──► pending ──► completed
                   └──► expired

State	Description
`storing`	Initial state. The platform is storing the identity verification details. This state transitions quickly to `pending`.
`pending`	The platform is actively running watchlist checks against the counterparty's PII.
`completed`	The verification has finished and an `outcome` is available.
`expired`	The verification expired before it could be completed. Create a new verification if this occurs.

Verification Outcomes

When the verification reaches the completed state, the outcome field indicates the result

Outcome	Description	Counterparty State
`passed`	The counterparty passed all watchlist screening checks	Changes to `verified`
`failed`	The counterparty failed one or more screening checks	Changes to `rejected`

Counterparty State Transitions

After verification completes, the counterparty's state automatically updates

Counterparty State	Description
`storing`	Counterparty is being stored (initial state)
`unverified`	Counterparty exists but has not been verified
`verified`	Counterparty passed verification
`rejected`	Counterparty failed verification

Compliance Decisions

The compliance_decisions array contains detailed information about each compliance check performed. The decision types depend on the counterparty type

For Individual Counterparties

Decision Type	Description
`person_watchlists`	Watchlist screening result for individuals

For Business Counterparties

Decision Type	Description
`business_watchlists`	Watchlist screening result for businesses

Compliance Decision States

State	Description
`passed`	The compliance check passed
`failed`	The compliance check failed
`expired`	The compliance decision has expired
`invalidated`	The compliance decision was invalidated

Failure Codes

If the verification outcome is failed, the failure_codes array will contain one or more of the following codes

Code	Description
`watchlist_check_failure`	The counterparty appears on a government or international watchlist or sanctions list
`pep_check_failure`	The counterparty is identified as a Politically Exposed Person (PEP)
`media_check_failure`	The counterparty appears on adverse media lists
`decision_timeout`	The verification timed out before a decision could be made
`requested_failure`	(Sandbox only) The caller requested that the verification fail using `expected_behaviours`

Monitoring Verification Status

Polling

Check the status of a verification by calling

GET /api/identity_verifications/{identity_verification_guid}
Authorization: Bearer YOUR_TOKEN

Poll this endpoint until the state changes to completed or expired.

Optional Query Parameters

Parameter	Type	Description
`include_pii`	boolean	Include PII in the response (requires identity_verifications:pii:read scope)

Response Fields (GET only)

The GET response includes an additional compliance_checks array not present in the POST response

Field	Type	Description
`compliance_checks`	array	Granular check results showing outcomes for each compliance check performed

{
  "guid": "{identity_verification_guid}",
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "{counterparty_guid}",
  "state": "completed",
  "outcome": "passed",
  "failure_codes": [],
  "compliance_decisions": [
    {
      "type": "person_watchlists",
      "state": "passed",
      "failure_codes": [],
      "expired_at": "2025-01-15T10:30:00.000Z"
    }
  ],
  "compliance_checks": [
    {
      "type": "person_watchlists",
      "outcome": "passed",
      "failure_codes": []
    }
  ]
}

{
  "guid": "{identity_verification_guid}",
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "{counterparty_guid}",
  "state": "completed",
  "outcome": "failed",
  "failure_codes": ["watchlist_check_failure"],
  "compliance_decisions": [
    {
      "type": "person_watchlists",
      "state": "failed",
      "failure_codes": ["watchlist_check_failure"],
      "expired_at": null
    }
  ],
  "compliance_checks": [
    {
      "type": "person_watchlists",
      "outcome": "failed",
      "failure_codes": ["watchlist_check_failure"]
    }
  ]
}

Verifying Counterparty State

After verification completes, confirm the counterparty's state updated by calling

GET /api/counterparties/{counterparty_guid}
Authorization: Bearer YOUR_TOKEN

Complete Example Flow

Step 1: Create a Counterparty (if not already created)

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "individual",
  "name": {
    "first": "John",
    "last": "Doe"
  },
  "address": {
    "street": "123 Main Street",
    "city": "New York",
    "subdivision": "NY",
    "postal_code": "10001",
    "country_code": "US"
  },
  "date_of_birth": "1985-06-15"
}

Step 2: Create the Identity Verification

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "{counterparty_guid_from_step_1}"
}

Step 3: Monitor Verification Status

Poll the identity verification endpoint

GET /api/identity_verifications/{identity_verification_guid}
Authorization: Bearer YOUR_TOKEN

Continue polling until state is completed or expired.

Step 4: Check the Outcome

If state is completed

If outcome is passed: The counterparty is now verified and can be used in transfers
If outcome is failed: Check failure_codes for the reason. The counterparty is now rejected

Business Counterparty Example

For business counterparties, the flow is identical but uses business-specific compliance decisions

Create Business Counterparty

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "business",
  "name": {
    "full": "Acme Corporation"
  },
  "address": {
    "street": "456 Business Ave",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country_code": "US"
  }
}

Verify Business Counterparty

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "{business_counterparty_guid}"
}

The response will include business_watchlists compliance decisions instead of person_watchlists.

Error Handling

Common Errors

Error Code	Cause	Resolution
`no_counterparty`	The specified counterparty GUID does not exist	Verify the counterparty_guid is correct
`rejected_counterparty`	The counterparty has already been rejected	Cannot verify a rejected counterparty
`incomplete_counterparty`	The counterparty creation has not yet completed	Wait for counterparty to finish storing
`invalid_value`	The counterparty is in an invalid state for verification	Ensure the counterparty is in `unverified` state
`data_exists`	A verification is already in progress for this counterparty	Wait for the existing verification to complete

Overview

Prerequisites

Creating a Verification

Parameters

Optional Parameters (Sandbox Only)

Sandbox Testing

Response

Verification States

Verification Outcomes

Counterparty State Transitions

Compliance Decisions

For Individual Counterparties

For Business Counterparties

Compliance Decision States

Failure Codes

Monitoring Verification Status

Polling

Optional Query Parameters

Response Fields (GET only)

Verifying Counterparty State

Complete Example Flow

Step 1: Create a Counterparty (if not already created)

Step 2: Create the Identity Verification

Step 3: Monitor Verification Status

Step 4: Check the Outcome

Business Counterparty Example

Create Business Counterparty

Verify Business Counterparty

Error Handling

Common Errors

Next Steps