--- title: "List contacts" method: GET path: "/contacts" tags: ["Contacts"] --- # List contacts `GET /contacts` ## Request - Base URL: `https://api.fireblocks.io/v1` - URL: `https://api.fireblocks.io/v1/contacts` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Query parameters - `pageCursor` string - `pageSize` integer - `includeTotal` boolean - `name` string - `types` string[] - `containerId` string, uuid - `archived` boolean - `accessControl` 'WHITELIST' | 'BLACKLIST' - `includeTagIds` string[] - `excludeTagIds` string[] - `sortBy` 'name' | 'updatedAt' - `order` 'ASC' | 'DESC' ## Response `200` A paginated list of contacts - ContactsPagedResponse - `data` Contact[], required: The page of contacts - `id` string, uuid, required: The unique identifier of the contact - `name` string, required: The contact name, unique across the workspace - `type` 'COUNTERPARTY' | 'OWN_ACCOUNT', required: Whether the contact is an external party or an account the workspace owns elsewhere - `accessControl` 'WHITELIST' | 'BLACKLIST': The access control applied to the contact. Absent when none is set. - `notes` string: Free-text notes on the contact. Absent when none are set. - `externalRefId` string: A customer-supplied reference id for the contact. Absent when none is set. - `containerId` string, uuid: The container holding the contact. Absent when the contact sits at the root. - `updatedAt` string, date-time, required: The date and time the contact was last modified, in ISO-8601 - `archivedAt` string, date-time: The date and time the contact was archived, in ISO-8601. Absent for live contacts, so this only carries a value when the request passed archived=true. - `tags` ContactTag[], required: The tags attached to the contact - `id` string, uuid, required: The unique identifier of the tag - `label` string, required: The tag label - `color` string: The tag color in hex format. Absent when the tag has none. - `description` string: Description for the tag. Absent when the tag has none. - `isProtected` boolean, required: Whether the tag is protected, meaning changes to it and to its attachments are approval-gated. - `pendingApprovalRequest` ContactApprovalRequest, nullable, required: An approval request awaiting a quorum decision. Null when none is open. Carried both by a contact, for a quorum-gated write on the contact itself, and by an individual tag, for a change to the tag's own definition. An attach or detach of that tag to this contact is carried by the tag's `pendingAttachment` instead. - `id` string, required: The approval request identifier - `type` string, required: The operation awaiting approval. Deliberately not an enumeration: the set is open across the surfaces that carry one, and includes contact operations such as CREATE_CONTACT and DELETE_CONTACT as well as changes to a tag itself. - `pendingAttachment` ContactTagAttachmentPending, nullable, required: An attach or detach of this tag to this contact awaiting a quorum decision. Null when the attachment is settled. Distinct from the tag's own `pendingApprovalRequest`, which covers a change to the tag itself rather than to this pairing. When both are open, this is the one to act on from a contact: cancelling a change to the tag's own definition belongs to the tag surface, and `pendingApprovalRequest.id` must not be used to cancel an attachment. - `action` 'ATTACH' | 'DETACH', required: The operation awaiting approval. ATTACH means the tag is not yet attached; DETACH means it is still attached, pending removal. - `approvalRequestId` string: The identifier of the approval request gating the operation - `pendingApprovalRequest` ContactApprovalRequest, nullable, required: An approval request awaiting a quorum decision. Null when none is open. Carried both by a contact, for a quorum-gated write on the contact itself, and by an individual tag, for a change to the tag's own definition. An attach or detach of that tag to this contact is carried by the tag's `pendingAttachment` instead. - `id` string, required: The approval request identifier - `type` string, required: The operation awaiting approval. Deliberately not an enumeration: the set is open across the surfaces that carry one, and includes contact operations such as CREATE_CONTACT and DELETE_CONTACT as well as changes to a tag itself. - `next` string: 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. - `total` integer: The number of contacts matching the filters, ignoring pagination. Present only when the request passed `includeTotal=true`; the key is absent otherwise. ## Other responses - `default`: Error Response --- [API](https://skmtc.dev/fireblocks/apis/fireblocks-api.md) - [All operations](https://skmtc.dev/fireblocks/apis/fireblocks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fireblocks/apis/fireblocks-api/revisions/4eba9965659a?raw)