List contacts

Lists contacts with cursor pagination.

GET /v1/contacts

Permission

The key must be granted contacts.read

A key without it gets 403 insufficient_scope, with the missing permission named in details.

has_more stays true while a full page comes back. A contact list is edited by the person paging through it, so a cursor is a position rather than a snapshot.

Query parameters

Field	Type	Description
`address_book_id`	string	Restrict to one address book.
`q`	string	Case-insensitive fragment match against the name and every address on the contact, including secondary ones.
`limit`	integer	1 to 200. Defaults to `50`
`cursor`	string	From the previous page's next_cursor. Opaque, and only meaningful with the same filters.

Request

curl https://api.veruapis.com/v1/contacts?address_book_id=01918e4b-2002-7f11-b4a9-0242ac130003&q=bob&limit=25 \
  -H "Authorization: Bearer vak_live_..."

Response

Field	Type	Description
`id`	string
`address_book_id`	string	Which book holds it.
`name`	string	The display name. Core calls this formatted_name; it is name here, because that is what every other resource in this API calls the human-readable string.
`given_name`	string
`family_name`	string
`emails`	object[]	Addresses, in stored order. The first is the one to compose to. Its fields are below.
`phones`	object[]	Numbers, in stored order. Its fields are below.
`organization`	string
`title`	string	Their job title, not a name prefix.
`notes`	string
`created_at`	RFC 3339
`updated_at`	RFC 3339

Each item in emails

Field	Type	Description
`address` required	string
`type`	string	A label such as work or home. Free text, not a closed set.

Each item in phones

Field	Type	Description
`number` required	string
`type`	string	A label such as cell or work.

{
  "data": [
  {
    "id": "01918e4b-2101-7f11-b4a9-0242ac130003",
    "address_book_id": "01918e4b-2002-7f11-b4a9-0242ac130003",
    "name": "Bob Smith",
    "given_name": "Bob",
    "family_name": "Smith",
    "emails": [
      { "address": "[email protected]", "type": "work" },
      { "address": "[email protected]", "type": "home" }
    ],
    "phones": [ { "number": "+37060000000", "type": "cell" } ],
    "organization": "Example Ltd",
    "title": "Buyer",
    "created_at": "2026-05-20T12:00:00Z",
    "updated_at": "2026-05-20T14:22:00Z"
  }
],
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" },
  "pagination": { "next_cursor": "eyJ1aWQiOjQyMTF9", "has_more": true, "limit": 25 }
}

Worth knowing

q matches the name and every address on the contact, including secondary ones, so searching for a colleague's old address still finds them.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

GET `/v1/contacts`

Your API key Used once, never stored. Query