FIfireblocks
Contacts

List contacts

Returns a paginated list of the workspace's address book contacts.

Live contacts are returned by default; pass archived=true to return only the archived ones. Results are sorted by name ascending unless sortBy/order say otherwise. Because the sort column is the page cursor's leading key, a pageCursor must be replayed with the same sort it was minted under, or the request is rejected.

Endpoint Permissions: any workspace role may read the address book. Writes are role-gated.

get/contacts

Request

Query parameters

pageCursorstring

Cursor indicating the page position. Omit to fetch the first page.

pageSizeinteger

Number of results per page

includeTotalboolean

Return the total count of matching contacts alongside the page. Counting is opt-in because it costs an extra pass over the filtered set; total is omitted from the response unless this is true.

namestring

Filter by a case-insensitive substring of the contact name

typesstring[]

Filter by one or more contact types

containerIdstring uuid

Filter by the container holding the contact

archivedboolean

Return only archived contacts instead of live ones

accessControl'WHITELIST' | 'BLACKLIST'

Filter by the access control applied to the contact

includeTagIdsstring[]

List of tag IDs to include. Contacts with any of these tags will be included

excludeTagIdsstring[]

List of tag IDs to exclude. Contacts with any of these tags will be filtered out

sortBy'name' | 'updatedAt'

The field to sort by

order'ASC' | 'DESC'

The sort direction

Response

A paginated list of contacts

nextstring

Cursor to the next page; absent when the current page is the last. Opaque, and bound to the sort that minted it — replay it unchanged and keep sortBy/order steady across pages.

totalinteger

The number of contacts matching the filters, ignoring pagination. Present only when the request passed includeTotal=true; the key is absent otherwise.

Example response

{
  "data": [
    {
      "id": "2f78ac4f-c409-4c56-9553-bc603fc0c932",
      "name": "Acme Corp",
      "type": "COUNTERPARTY",
      "accessControl": "WHITELIST",
      "notes": "Primary OTC desk",
      "externalRefId": "crm-4471",
      "containerId": "11111111-1111-1111-1111-111111111111",
      "updatedAt": "2026-08-06T12:00:00.000Z",
      "tags": [
        {
          "id": "df4c0987-30da-4976-8dcf-bc2dd41ae331",
          "label": "VIP",
          "color": "#FF5733",
          "description": "Tag for VIP counterparties",
          "isProtected": false,
          "pendingApprovalRequest": null,
          "pendingAttachment": null
        }
      ],
      "pendingApprovalRequest": null
    }
  ],
  "next": "bmFtZS1BU0M=~QWNtZSBDb3Jw:NA==",
  "total": 42
}

Changes

No recorded changes to this operation across all 1 revision of this API.