List contacts

Find people in the organization's contacts (People in the Dashboard), newest first by default. q matches names, channel profile names, usernames, phones, emails, identity documents and contact ids (ignoring accents, case and number formatting); channelType, agentId, handling (ai: the AI took part in one of their conversations; team: only people answered) and lastContactedAfter narrow it; sort is created, name or last_contacted. Each person carries their latest conversation; count_contacts counts every match. Start here to get a contactId; with several matches, ask which person is meant. Next: get_contact, or list_conversations with contactId for their conversations.

Scopes: any one of raiz:contacts:read, raiz:contacts:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: response up to 1 MB
CLI: arbol raiz contacts list · MCP tool: raiz_contacts_list

GET

https://api.getarbol.com/v1/raiz/contacts

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes raiz:contacts:read, raiz:contacts:write. Get an API key.

Query parameters

cursor
optional
string
Opaque cursor returned by pageInfo; omit it to request the first page.
direction
optional
forward
or
backward
Direction to traverse the stable keyset ordering from the supplied cursor.

default: "forward"
limit
optional
integer
Maximum items returned in one page. Defaults to 25; larger reads require another cursor.

maximum: 100 · minimum: 1 · default: 25
agentId
optional
string
People with a conversation with this Agent.

pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
channelType
optional
string
Comma-separated channel types: people with a conversation on one of them.

pattern: ^(voice|whatsapp|web)(,(voice|whatsapp|web))*$
handling
optional
ai
or
team
ai: people with a conversation the AI took part in. team: people whose conversations only the organization's people answered.
lastContactedAfter
optional
string
Last in touch at or after this instant (RFC 3339).

format: date-time
q
optional
string
Search by name (words in any order, ignoring accents and case), channel profile name, username, phone, email, identity document or contact id. Phone and document formatting is ignored; partial numbers match, including a phone without its country prefix. Searches saved identities, not people merely mentioned in messages.

maxLength: 200 · minLength: 1
sort
optional
created
or
name
or
last_contacted
created (newest first), name (A–Z) or last_contacted (most recent first).

default: "created"

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  conversationCount
  integer
  required
  minimum: 0
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  email
  string | null
  required
  Preferred email.
  
  familyName
  string | null
  required
  fullName
  string | null
  required
  Given and family name.
  
  givenName
  string | null
  required
  id
  string
  required
  Contact id.
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  lastContactedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  lastConversation
  required
  One of the following:
  RaizContactLastConversation
  agentName
  string | null
  required
  agentReplied
  boolean
  required
  The Agent answered it.
  
  aiEnabled
  boolean
  required
  aiPaused
  boolean
  required
  aiPausedBy
  agent
  or
  operator
  or
  null
  required
  channelType
  voice
  or
  whatsapp
  or
  web
  required
  closeReason
  string | null
  required
  id
  string
  required
  Conversation id.
  
  pattern: ^cnv_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  operatorReplied
  boolean
  required
  People answered it.
  
  startedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  status
  open
  or
  closed
  required
  title
  string | null
  required
  null
  metadata
  object
  required
  Your own keys and labels for this resource (up to 50 keys of 40 characters; values up to 500 characters). Raíz never interprets them.
  
  nameAuthor
  person
  or
  ai
  or
  system
  or
  import
  or
  provider
  or
  null
  required
  Who wrote the value.
  
  phone
  string | null
  required
  Preferred phone number.
  
  postalAddresses
  array of
  object
  required
  city
  optional
  string
  maxLength: 120
  countryCode
  optional
  string
  ISO 3166-1 alpha-2.
  
  pattern: ^[A-Z]{2}$
  line
  optional
  array of
  string
  maxLength: 200
  postalCode
  optional
  string
  maxLength: 20
  state
  optional
  string
  maxLength: 120
  use
  optional
  home
  or
  work
  profileName
  string | null
  required
  The name the person shows on WhatsApp, as WhatsApp sent it. Read-only; fullName is the saved name.
  
  summary
  string | null
  required
  summaryAuthor
  person
  or
  ai
  or
  system
  or
  import
  or
  provider
  or
  null
  required
  Who wrote the value.
  
  updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  version
  integer
  required
  minimum: 1
  facts
  array of
  object
  required
  The current value of each definition for this subject (the newest assertion that was not rejected).
  
  author
  person
  or
  ai
  or
  system
  or
  import
  or
  provider
  required
  Who wrote the value.
  
  confidence
  number | null
  required
  How sure the AI was, from 0 to 1. Null for people.
  
  maximum: 1 · minimum: 0
  contactId
  string | null
  required
  The contact the fact is about, for contact facts.
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  conversationId
  string | null
  required
  The conversation the fact is about, for conversation facts.
  
  pattern: ^cnv_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  definition
  object
  required
  id
  string
  required
  Definition id.
  
  pattern: ^def_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  key
  string
  required
  kind
  attribute
  or
  assessment
  or
  category
  or
  metric
  required
  What the definition captures: an attribute (a datum), an assessment (a yes/no check of the conversation), a category (a classification such as the reason for contact) or a metric.
  
  name
  string
  required
  valueType
  text
  or
  number
  or
  boolean
  or
  date
  or
  option
  required
  id
  string
  required
  Fact id.
  
  pattern: ^fct_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  observedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  optionLabel
  string | null
  required
  The option's label, for option facts.
  
  reviewStatus
  unreviewed
  or
  confirmed
  or
  rejected
  required
  value
  required
  A string (text), number, boolean, ISO date YYYY-MM-DD (date) or option key (option), per the definition's value type.
  
  One of the following:
  string
  number
  boolean
  null
  valueStatus
  known
  or
  unknown
  or
  not_applicable
  required
  identifiers
  array of
  object
  required
  countryCode
  string
  required
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  id
  string
  required
  Identity document id.
  
  pattern: ^(?:cid_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:idn)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  number
  string
  required
  type
  string
  required
  verifiedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  points
  array of
  object
  required
  address
  string
  required
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  id
  string
  required
  Contact point id.
  
  pattern: ^(?:cpt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:idn)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  kind
  phone
  or
  email
  or
  whatsapp
  or
  telegram
  or
  slack
  or
  web
  required
  label
  string | null
  required
  preferred
  boolean
  required
  verifiedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  timeline
  optional
  object
  What happened to the contact (and to the duplicates it absorbed), newest first. Present only when expanded.
  
  data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  author
  person
  or
  ai
  or
  system
  or
  import
  or
  provider
  or
  null
  required
  Who wrote the value.
  
  detail
  string | null
  required
  Item-specific detail: the channel of a conversation, a fact's value status, the changed fields of a change or the reason of a merge.
  
  id
  string
  required
  Id of the conversation, fact, change or merge the item stands for.
  
  occurredAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  summary
  string | null
  required
  Conversation title, definition name, <resource>.<action> of a change, or the absorbed contact's id for a merge.
  
  type
  conversation
  or
  fact
  or
  change
  or
  merge
  required
  object
  string
  required
  Discriminator for a resource list response.
  
  pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
- object
  string
  required
  Discriminator for a resource list response.
- pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.
INVALID_CURSOR: The cursor is malformed or belongs to a different list.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}