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

TypeScript

const response: Promise<FireblocksResponse<ContactsPagedResponse>> = fireblocks.contacts.getContacts(contactsApiGetContactsRequest);

CompletableFuture<ApiResponse<ContactsPagedResponse>> response = fireblocks.contacts().getContacts(pageCursor, pageSize, includeTotal, name, types, containerId, archived, accessControl, includeTagIds, excludeTagIds, sortBy, order);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/contacts"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "message": "<string>",
  "code": 123
}

Query Parameters

pageCursor

string

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

Maximum string length: 1024

pageSize

integer

default:100

Number of results per page

Required range: 1 <= x <= 100

includeTotal

boolean

default:false

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.

name

string

Filter by a case-insensitive substring of the contact name

Required string length: 1 - 255

types

enum<string>[]

Filter by one or more contact types

Maximum array length: 2

Available options:

COUNTERPARTY,

OWN_ACCOUNT

containerId

string<uuid>

Filter by the container holding the contact

archived

boolean

default:false

Return only archived contacts instead of live ones

accessControl

enum<string>

Filter by the access control applied to the contact

Available options:

WHITELIST,

BLACKLIST

includeTagIds

string<uuid>[]

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

Maximum array length: 50

excludeTagIds

string<uuid>[]

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

Maximum array length: 50

sortBy

enum<string>

default:name

The field to sort by

Available options:

name,

updatedAt

order

enum<string>

default:ASC

The sort direction

Available options:

ASC,

DESC

Response

A paginated list of contacts

data

object[]

required

The page of contacts

Show child attributes

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
  }
]

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.

Example:

"bmFtZS1BU0M=~QWNtZSBDb3Jw:NA=="

total

integer

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

Example:

42

⌘I

TypeScript

const response: Promise<FireblocksResponse<ContactsPagedResponse>> = fireblocks.contacts.getContacts(contactsApiGetContactsRequest);

CompletableFuture<ApiResponse<ContactsPagedResponse>> response = fireblocks.contacts().getContacts(pageCursor, pageSize, includeTotal, name, types, containerId, archived, accessControl, includeTagIds, excludeTagIds, sortBy, order);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/contacts"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "message": "<string>",
  "code": 123
}

Introduction

Errors & Statuses

Data Objects

API Endpoints

List contacts

Query Parameters

Response