Fireblocks Contacts API

openapi: 3.2.0
info:
  title: Fireblocks Contacts API
  description: 'Fireblocks provides a suite of applications to manage digital asset operations and a complete development platform to build your business on the blockchain.


    - Visit our website for more information: Fireblocks Website

    - Visit our developer docs: Fireblocks DevPortal'
  version: 1.6.2
  contact:
    email: developers@fireblocks.com
servers:
- url: https://api.fireblocks.io/v1
  description: Fireblocks Production Environment Base URL
- url: https://sandbox-api.fireblocks.io/v1
  description: Fireblocks Sandbox Environment Base URL
tags:
- name: Contacts
paths:
  /contacts:
    get:
      operationId: getContacts
      summary: List contacts
      description: '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.'
      tags:
      - Contacts
      x-rate-limit-category: query
      parameters:
      - in: query
        name: pageCursor
        required: false
        description: Cursor indicating the page position. Omit to fetch the first page.
        schema:
          type: string
          maxLength: 1024
        example: bmFtZS1BU0M=~QWNtZSBDb3Jw:NA==
      - in: query
        name: pageSize
        required: false
        description: Number of results per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        example: 25
      - in: query
        name: includeTotal
        required: false
        description: 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`.
        schema:
          type: boolean
          default: false
        example: true
      - in: query
        name: name
        required: false
        description: Filter by a case-insensitive substring of the contact name
        schema:
          type: string
          minLength: 1
          maxLength: 255
        example: acme
      - in: query
        name: types
        required: false
        description: Filter by one or more contact types
        schema:
          type: array
          maxItems: 2
          items:
            type: string
            enum:
            - COUNTERPARTY
            - OWN_ACCOUNT
        example:
        - COUNTERPARTY
      - in: query
        name: containerId
        required: false
        description: Filter by the container holding the contact
        schema:
          type: string
          format: uuid
        example: 11111111-1111-1111-1111-111111111111
      - in: query
        name: archived
        required: false
        description: Return only archived contacts instead of live ones
        schema:
          type: boolean
          default: false
        example: false
      - in: query
        name: accessControl
        required: false
        description: Filter by the access control applied to the contact
        schema:
          type: string
          enum:
          - WHITELIST
          - BLACKLIST
        example: WHITELIST
      - in: query
        name: includeTagIds
        required: false
        description: List of tag IDs to include. Contacts with any of these tags will be included
        schema:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid
        example:
        - df4c0987-30da-4976-8dcf-bc2dd41ae331
      - in: query
        name: excludeTagIds
        required: false
        description: List of tag IDs to exclude. Contacts with any of these tags will be filtered out
        schema:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid
        example:
        - df4c0987-30da-4976-8dcf-bc2dd41ae331
      - in: query
        name: sortBy
        required: false
        description: The field to sort by
        schema:
          type: string
          enum:
          - name
          - updatedAt
          default: name
        example: updatedAt
      - in: query
        name: order
        required: false
        description: The sort direction
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: ASC
        example: DESC
      responses:
        '200':
          description: A paginated list of contacts
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactsPagedResponse'
        default:
          $ref: '#/components/responses/Error'
      x-readme:
        code-samples:
        - language: typescript
          code: 'const response: Promise<FireblocksResponse<ContactsPagedResponse>> = fireblocks.contacts.getContacts(contactsApiGetContactsRequest);'
          name: Fireblocks SDK TypeScript example
        - language: java
          code: CompletableFuture<ApiResponse<ContactsPagedResponse>> response = fireblocks.contacts().getContacts(pageCursor, pageSize, includeTotal, name, types, containerId, archived, accessControl, includeTagIds, excludeTagIds, sortBy, order);
          name: Fireblocks SDK Java example
        - language: python
          code: response = fireblocks.contacts.get_contacts(page_cursor, page_size, include_total, name, types, container_id, archived, access_control, include_tag_ids, exclude_tag_ids, sort_by, order);
          name: Fireblocks SDK Python example
      x-codeSamples:
      - lang: TypeScript
        source: 'const response: Promise<FireblocksResponse<ContactsPagedResponse>> = fireblocks.contacts.getContacts(contactsApiGetContactsRequest);'
      - lang: Java
        source: CompletableFuture<ApiResponse<ContactsPagedResponse>> response = fireblocks.contacts().getContacts(pageCursor, pageSize, includeTotal, name, types, containerId, archived, accessControl, includeTagIds, excludeTagIds, sortBy, order);
      - lang: Python
        source: response = fireblocks.contacts.get_contacts(page_cursor, page_size, include_total, name, types, container_id, archived, access_control, include_tag_ids, exclude_tag_ids, sort_by, order);
components:
  schemas:
    ContactApprovalRequest:
      type:
      - object
      - 'null'
      description: 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.
      properties:
        id:
          type: string
          description: The approval request identifier
          example: '12345'
        type:
          type: string
          description: '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.'
          example: CREATE_CONTACT
      required:
      - id
      - type
    ContactTagAttachmentPending:
      type:
      - object
      - 'null'
      description: '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.'
      properties:
        action:
          type: string
          description: The operation awaiting approval. ATTACH means the tag is not yet attached; DETACH means it is still attached, pending removal.
          enum:
          - ATTACH
          - DETACH
          example: ATTACH
        approvalRequestId:
          type: string
          description: The identifier of the approval request gating the operation
          example: '12345'
      required:
      - action
    ErrorSchema:
      type: object
      properties:
        message:
          type: string
        code:
          type: number
    ContactsPagedResponse:
      type: object
      properties:
        data:
          type: array
          description: The page of contacts
          items:
            $ref: '#/components/schemas/Contact'
          example:
          - 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:
          type: string
          description: 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.
          example: bmFtZS1BU0M=~QWNtZSBDb3Jw:NA==
        total:
          type: integer
          description: The number of contacts matching the filters, ignoring pagination. Present only when the request passed `includeTotal=true`; the key is absent otherwise.
          example: 42
      required:
      - data
    ContactTag:
      type: object
      description: A tag attached to the contact, with the display details resolved from the tagging service.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the tag
          example: df4c0987-30da-4976-8dcf-bc2dd41ae331
        label:
          type: string
          description: The tag label
          example: VIP
        color:
          type: string
          description: The tag color in hex format. Absent when the tag has none.
          example: '#FF5733'
        description:
          type: string
          description: Description for the tag. Absent when the tag has none.
          example: Tag for VIP counterparties
        isProtected:
          type: boolean
          description: Whether the tag is protected, meaning changes to it and to its attachments are approval-gated.
          example: false
        pendingApprovalRequest:
          $ref: '#/components/schemas/ContactApprovalRequest'
        pendingAttachment:
          $ref: '#/components/schemas/ContactTagAttachmentPending'
      required:
      - id
      - label
      - isProtected
      - pendingApprovalRequest
      - pendingAttachment
    Contact:
      type: object
      description: A contact in the workspace address book.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the contact
          example: 2f78ac4f-c409-4c56-9553-bc603fc0c932
        name:
          type: string
          description: The contact name, unique across the workspace
          example: Acme Corp
        type:
          type: string
          description: Whether the contact is an external party or an account the workspace owns elsewhere
          enum:
          - COUNTERPARTY
          - OWN_ACCOUNT
          example: COUNTERPARTY
        accessControl:
          type: string
          description: The access control applied to the contact. Absent when none is set.
          enum:
          - WHITELIST
          - BLACKLIST
          example: WHITELIST
        notes:
          type: string
          description: Free-text notes on the contact. Absent when none are set.
          example: Primary OTC desk
        externalRefId:
          type: string
          description: A customer-supplied reference id for the contact. Absent when none is set.
          example: crm-4471
        containerId:
          type: string
          format: uuid
          description: The container holding the contact. Absent when the contact sits at the root.
          example: 11111111-1111-1111-1111-111111111111
        updatedAt:
          type: string
          format: date-time
          description: The date and time the contact was last modified, in ISO-8601
          example: '2026-08-06T12:00:00.000Z'
        archivedAt:
          type: string
          format: date-time
          description: 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.
          example: '2026-08-07T11:00:00.000Z'
        tags:
          type: array
          description: The tags attached to the contact
          items:
            $ref: '#/components/schemas/ContactTag'
          example:
          - id: df4c0987-30da-4976-8dcf-bc2dd41ae331
            label: VIP
            color: '#FF5733'
            description: Tag for VIP counterparties
            isProtected: false
            pendingApprovalRequest: null
            pendingAttachment: null
        pendingApprovalRequest:
          $ref: '#/components/schemas/ContactApprovalRequest'
      required:
      - id
      - name
      - type
      - updatedAt
      - tags
      - pendingApprovalRequest
  responses:
    Error:
      description: Error Response
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSchema'
  headers:
    X-Request-ID:
      schema:
        type: string
      description: Unique ID correlated to the API request. Please provide it in any support ticket you create or on Github issues related to Fireblocks SDKs
  securitySchemes:
    bearerTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
x-readme:
  explorer-enabled: false
  samples-languages:
  - curl
  - javascript
  - python
x-provenance:
  method: harvested
  publisher: Fireblocks
  source: https://swagger.fireblocks.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)