list_contacts — Paginated contacts for an organization

The list_contacts tool returns a paginated list of contacts for a single organization. Contacts are the customers an organization invoices. Every request must include intent and organizationId, and the token must carry the contacts.read scope.

Receivables tools require the organization to have invoicing set up in Relay. If it does not, the tool returns an error instead of data.

Scope

Required OAuth scope: contacts.read

Input

string

required

The organization to query. Must be one of the organizations the token can access.

string

Free-text search across contact fields. Must be 1 to 200 characters.

string

Filter by contact status. Allowed values: active, archived. Defaults to active.

string

Opaque pagination cursor from a previous response. Keep the same pageSize and filters when following cursors. Never parse, edit, or reuse a cursor across different filter sets.

integer

Number of results per page. Must be between 1 and 100. Defaults to 50.

string

required

What the user asked for and why this call serves it, in 1 to 500 characters. Required on every tool call. See Common tool arguments.

Output

Contact[]

required

Array of contacts matching the filters.

Show Contact

string

required

Unique contact identifier. Use this value as contactId.

string

required

Organization the contact belongs to.

string

required

Contact status. Values: active, archived.

string

required

Display name of the contact.

string

required

Email address of the contact.

string

required

Phone number of the contact.

object | null

required

Postal address of the contact, or null when none is on file.

string

required

Where the contact was created or synced from. Values: relay, quickbooks, xero, import.

string

required

Timestamp when the contact was created, in RFC 3339 format.

string

required

Timestamp when the contact was last updated, in RFC 3339 format.

object

required

Cursor-based pagination metadata.

Show Pagination

boolean

required

Whether more results are available.

integer

required

Number of results in this page.

string

Opaque cursor to fetch the next page. Present only when hasNextPage is true.

Example

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "list_contacts",
    "arguments": {
      "intent": "User asked for the billing email of their customer Northwind.",
      "organizationId": "org_1",
      "search": "Northwind",
      "pageSize": 10
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "structuredContent": {
      "data": [
        {
          "id": "ct_1",
          "organizationId": "org_1",
          "status": "active",
          "name": "Northwind Traders",
          "email": "billing@example.com",
          "phoneNumber": "+1 555 010 0100",
          "address": null,
          "source": "relay",
          "createdAt": "2026-03-02T15:04:00.000Z",
          "updatedAt": "2026-09-14T10:22:00.000Z"
        }
      ],
      "pagination": {
        "hasNextPage": false,
        "pageSize": 10
      }
    }
  }
}

Notes

Only active contacts are returned unless you pass status: "archived".
source shows whether the contact was created in Relay or synced from an accounting integration.
Follow nextCursor until hasNextPage is false. Keep the same pageSize and filters on every page.

get_contact

Fetch a single contact by ID.

Result conventions

Learn how pagination, Money objects, and dual-channel output work across all tools.

Organizations

Transactions

Accounts

Cards

Statements

Contacts

Catalog items

Invoices

list_contacts — Paginated contacts for an organization

Scope

Input

Output

Example

Notes

get_contact

Result conventions

​Scope

​Input

​Output

​Example

​Notes

get_contact

Result conventions

Scope

Input

Output

Example

Notes