Create a contact

Add a person with their contact points (phones, WhatsApp, emails) and identity documents. Search with list_contacts first to avoid duplicates: it fails with ADDRESS_IN_USE or IDENTIFIER_IN_USE when another contact already has one of them, and nothing is created. For many people at once, use import_contacts.

Scope: raiz:contacts:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; not idempotent: check the outcome before you retry
Limits: request body up to 32 KB, response up to 1 MB
CLI: arbol raiz contacts create · MCP tool: raiz_contacts_create

POST

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 the scope raiz:contacts:write. Get an API key.

Request body JSON required

familyName
optional
string | null
maxLength: 160 · minLength: 1
givenName
optional
string | null
maxLength: 160 · minLength: 1
identifiers
optional
array of
object
Identity documents. In an update, the complete new set: documents not listed are removed.
- number
  string
  required
  Document number, upper case letters and digits only.
  
  pattern: ^[A-Z0-9]{3,20}$
- type
  string
  required
  Document type code, for example CC, CE, PA, TI.
  
  pattern: ^[A-Z]{2,4}$
- countryCode
  optional
  string
  Issuing country, ISO 3166-1 alpha-2.
  
  pattern: ^[A-Z]{2}$ · default: "CO"
}
metadata
optional
object
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.
points
optional
array of
Phones, emails and other addresses. In an update, the complete new set: points not listed are removed; listed ones keep their id and verification.
One of the following:
object
object
object
}
postalAddresses
optional
array of
object
- 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
}
summary
optional
string | null
maxLength: 4000

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- 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.
}
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.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

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
}

409

ADDRESS_IN_USE: Another contact in this organization already uses this address.
IDENTIFIER_IN_USE: Another contact in this organization already has this identity document.
VERSION_CONFLICT: The resource changed after it was read. Read it again and retry with the new version.

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
}