Contact

19 min

Address-book endpoints manage organization-scoped contacts used as transaction parties. Contact creation and updates can require approval before the resulting contact is usable.

List contacts

GET /api/external/contacts/?limit={limit}&cursor={cursor}&{filters}

Query parameters

Parameter	Type	Required	Description
limit	number	No	Requested page size. SDK default: 20.
cursor	string \| null	No	Cursor for the next page.
Filters	Record<string, string>	No	Contact filters, for example name, status, or externalId when supported.

Request example

{
  "query": {
    "limit": 20,
    "cursor": null,
    "status": "PENDING"
  }
}

Response

interface ContactListResponse {
  results: Contact[];
  nextCursor?: string | null;
  hasNext?: boolean;
}

JSON example

{
  "results": [
    {
      "id": "contact_123",
      "orgId": "org_456",
      "subOrgId": "sub_org_123",
      "name": "Operations Wallet",
      "blockChain": "ETHEREUM",
      "address": "0xAbC1234567890abcdef1234567890abcdef1234",
      "status": "PENDING",
      "tags": [
        "vendor",
        "priority"
      ],
      "createdById": "api_user_123",
      "externalId": "vendor-1001",
      "assetList": [
        "USDC",
        "ETH"
      ],
      "createdAt": "2026-08-04T10:30:00Z",
      "updatedAt": "2026-08-04T10:30:00Z",
      "isDeleted": false
    }
  ],
  "nextCursor": "eyJpZCI6ImNvbnRhY3RfMTIzIn0=",
  "hasNext": true
}

JavaScript SDK

getContacts(
  params?: Record<string, string>,
  limit?: number,
  cursor?: string | null,
): Promise<ContactListResponse>

Retrieve a contact

GET /api/external/contacts/{contactId}/

Request example

{
  "path": {
    "contactId": "contact_123"
  }
}

Response

{
  "id": "contact_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "name": "Operations Wallet",
  "blockChain": "ETHEREUM",
  "address": "0xAbC1234567890abcdef1234567890abcdef1234",
  "status": "PENDING",
  "tags": [
    "vendor",
    "priority"
  ],
  "createdById": "api_user_123",
  "externalId": "vendor-1001",
  "assetList": [
    "USDC",
    "ETH"
  ],
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false
}

JavaScript SDK

getContactById(contactId: string): Promise<Contact>

Create a contact

POST /api/external/contacts/

REST request body

{
  "name": "Operations Wallet",
  "subOrgId": "sub_org_123",
  "address": "0xAbC123...",
  "blockChain": "ETHEREUM",
  "tags": ["vendor", "priority"],
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "contactGroupIds": ["contact_group_123"]
}

Field	Type	Required	Description
name	string	Yes	Contact display name.
subOrgId	string	No	Sub-organization that owns the contact.
address	string	Yes	Destination address on the selected chain.
blockChain	string	Yes	REST field. The SDK accepts this as chain.
tags	string[]	No	Searchable contact tags.
externalId	string	No	Client-controlled reference.
assetList	string[]	No	Assets permitted for the contact. The SDK serializes an omitted value as an empty array.
contactGroupIds	string[]	No	Organization-scoped contact groups to attach.

Response

{
  "id": "contact_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "name": "Operations Wallet",
  "blockChain": "ETHEREUM",
  "address": "0xAbC123...",
  "status": "PENDING",
  "tags": ["vendor", "priority"],
  "createdById": "api_user_123",
  "externalId": "vendor-1001",
  "assetList": ["USDC", "ETH"],
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false
}

JavaScript SDK

interface CreateContactRequest {
  name: string;
  subOrgId?: string;
  address: string;
  chain: string;
  tags?: string[];
  externalId?: string;
  assetList?: string[];
  contactGroupIds?: string[];
}

createContact(request: CreateContactRequest): Promise<Contact>

Approval flow

const contact = await apiClient.createContact(request);
const approved = await apiClient.createContactApproval(contact);

// Convenience helper: create, then approve.
const approvedContact = await apiClient.createContactWithApproval(request);

Update contact asset and group assignments

PUT /api/external/contacts/{contactId}/

The current SDK update contract changes only assetList and contactGroupIds. It does not rename the contact or replace its address.

REST request body

{
  "assetList": ["USDC"],
  "contactGroupIds": ["contact_group_123"]
}

Response

{
  "id": "contact_123",
  "name": "Operations Wallet",
  "address": "0xAbC1234567890abcdef1234567890abcdef1234",
  "blockChain": "ETHEREUM",
  "tags": [
    "vendor",
    "priority"
  ],
  "externalId": "vendor-1001",
  "assetList": [
    "USDC"
  ]
}

JavaScript SDK

interface UpdateContactRequest {
  id: string;
  assetList?: string[];
  contactGroupIds?: string[];
}

updateContact(request: UpdateContactRequest): Promise<UpdateContactResponse>
updateContactWithApproval(request: UpdateContactRequest): Promise<Contact>