Skip to main content

Manage contacts

Beta

Contacts v3 is in beta and may change as we continue to improve it. Please review the documentation and endpoints carefully, test everything in the sandbox, and reach out to the Solutions team if you need help.

Contacts store the originator and beneficiary details required for Travel Rule compliance. Create a contact once, then reference it by contactId in later payment requests instead of passing inline partyDetails each time.

Use contacts when you:

  • Repeatedly send or receive payments involving the same counterparty.
  • Want to avoid duplicating party details across payment links, channels, and payouts.
  • Need a central registry of known originators and beneficiaries for compliance purposes.
Contact validation

Contacts are validated when you create a payment, not when you create a contact. This means a contact can be created with minimal details but later fail validation if the payment requires additional Travel Rule fields, for example, for crypto payments above a certain threshold.

Create a contact​

Create a contact by sending a POST /platform/v3/contacts request. A contact can represent either an individual (natural person) or a company (legal entity).

The response includes the generated id that you use as contactId in payment requests:

List contacts​

Retrieve a paginated list of your contacts by sending a GET /platform/v3/contacts request.

Use the q parameter to narrow down results. For example, to find all individual third-party contacts whose name contains "Jane":

/platform/v3/contacts?size=10&page=0&q=searchTerm:Jane type:INDIVIDUAL relationshipType:THIRD_PARTY

In the response, you receive the list of available contacts.

Get a contact​

Retrieve a single contact by sending a GET /platform/v3/contacts/{contactId} request.

Update a contact​

Replace all fields of an existing contact by sending a PUT /platform/v3/contacts/{contactId} request. You must supply the full payload including the entity object. The request body matches the create contact request.

Delete a contact​

Remove a contact that is no longer needed by sending a DELETE /platform/v3/contacts/{contactId} request. Returns 204 No Content on success.

warning

A contact that is currently referenced by an active payment cannot be deleted.

Use contacts in payments​

Once created, reference the contact id as contactId in payment creation requests. This replaces inline partyDetails and simplifies your integration.

For example, when creating a payment channel, you can pass a contactId instead of the full partyDetails object:

{
  "walletId": "a:24092328494070:G5i4XZ9:1",
  "payCurrency": "ETH",
  "displayCurrency": "EUR",
  "reference": "c1b933d5-3354-4f83-a05f-0b53f1be85f2",
  "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.1",
    "contactId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
warning

You cannot pass both partyDetails and contactId in the same request; doing so will return an error.

The platform resolves the contact and validates its details against the Travel Rule requirements when the payment is created.

For details on the specific validation requirements for each payment type, see:

Was this page helpful?
Last updated on