> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a contact

> Updates one tenant-owned Contact under contacts:write; supplied identity and address arrays replace their complete sets. There is no idempotency key, so inspect current state before replaying an uncertain request.



## OpenAPI

````yaml https://api.getarbol.com/openapi.json patch /contacts/{id}
openapi: 3.1.2
info:
  contact:
    email: support@getarbol.com
    name: Arbol
    url: https://docs.getarbol.com
  description: >-
    Provider-neutral API for creating and operating Arbol agents, contacts,
    conversations, channels, knowledge, integrations, and evaluations. Every
    request is bound to one Auth0 Organization.
  title: Arbol API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.getarbol.com/v1
security: []
paths:
  /contacts/{id}:
    patch:
      tags:
        - Contacts
      summary: Update a contact
      description: >-
        Updates one tenant-owned Contact under contacts:write; supplied identity
        and address arrays replace their complete sets. There is no idempotency
        key, so inspect current state before replaying an uncertain request.
      operationId: updateContact
      parameters:
        - in: path
          required: true
          name: id
          schema:
            $ref: '#/components/schemas/ArbolResourceId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                details:
                  type: object
                  properties:
                    addresses:
                      maxItems: 20
                      type: array
                      items:
                        type: object
                        properties:
                          city:
                            anyOf:
                              - type: string
                                maxLength: 160
                              - type: 'null'
                          country:
                            anyOf:
                              - type: string
                                maxLength: 100
                              - type: 'null'
                          id:
                            type: string
                            minLength: 1
                            maxLength: 100
                          isPrimary:
                            type: boolean
                          label:
                            anyOf:
                              - type: string
                                maxLength: 100
                              - type: 'null'
                          postalCode:
                            anyOf:
                              - type: string
                                maxLength: 40
                              - type: 'null'
                          state:
                            anyOf:
                              - type: string
                                maxLength: 160
                              - type: 'null'
                          street:
                            anyOf:
                              - type: string
                                maxLength: 500
                              - type: 'null'
                          type:
                            type: string
                            minLength: 1
                            maxLength: 80
                        required:
                          - city
                          - country
                          - isPrimary
                          - label
                          - postalCode
                          - state
                          - street
                          - type
                        additionalProperties: false
                  required:
                    - addresses
                  additionalProperties: false
                familyName:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 160
                    - type: 'null'
                givenName:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 160
                    - type: 'null'
                identities:
                  maxItems: 12
                  type: array
                  items:
                    type: object
                    properties:
                      address:
                        type: string
                        minLength: 1
                        maxLength: 500
                      kind:
                        $ref: '#/components/schemas/UserWritableContactIdentityKind'
                      id:
                        $ref: '#/components/schemas/ArbolResourceId'
                      isPrimary:
                        default: false
                        type: boolean
                    required:
                      - address
                      - kind
                    additionalProperties: false
                summary:
                  anyOf:
                    - type: string
                      maxLength: 4000
                    - type: 'null'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactOutput'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '400':
          description: >-
            Inferable validation failure or a non-inferable malformed transport
            request.
          content:
            application/json:
              schema:
                oneOf:
                  - oneOf:
                      - $ref: '#/components/schemas/BadRequest'
                      - $ref: '#/components/schemas/UndefinedError'
                  - $ref: '#/components/schemas/TransportBadRequestError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Unauthorized'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '403':
          description: The caller is not allowed to perform this operation.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Forbidden'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/NotFound'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '409':
          description: An identity is already assigned
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Conflict3'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '413':
          $ref: '#/components/responses/TransportPayloadTooLarge'
        '415':
          $ref: '#/components/responses/TransportUnsupportedMediaType'
        '422':
          description: A contact identity is invalid
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UnprocessableContent'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
      security:
        - userOAuth:
            - org:use
            - contacts:write
        - machineOAuth:
            - contacts:write
components:
  schemas:
    ArbolResourceId:
      type: string
      maxLength: 64
      pattern: >-
        ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: >-
        Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup
        determine its resource type.
      examples:
        - agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31
      title: Arbol resource ID
    UserWritableContactIdentityKind:
      type: string
      enum:
        - phone
        - email
        - telegram_user
        - slack_user
        - web
        - document
      description: >-
        Contact identity namespace writable by a user; provider-owned identities
        such as WhatsApp user ids are excluded.
      title: User-writable Contact identity kind
    ContactOutput:
      type: object
      properties:
        createdAt:
          $ref: '#/components/schemas/IsoDatetime'
        details:
          type: object
          properties:
            addresses:
              maxItems: 20
              type: array
              items:
                type: object
                properties:
                  city:
                    anyOf:
                      - type: string
                        maxLength: 160
                      - type: 'null'
                  country:
                    anyOf:
                      - type: string
                        maxLength: 100
                      - type: 'null'
                  id:
                    type: string
                    minLength: 1
                    maxLength: 100
                  isPrimary:
                    type: boolean
                  label:
                    anyOf:
                      - type: string
                        maxLength: 100
                      - type: 'null'
                  postalCode:
                    anyOf:
                      - type: string
                        maxLength: 40
                      - type: 'null'
                  state:
                    anyOf:
                      - type: string
                        maxLength: 160
                      - type: 'null'
                  street:
                    anyOf:
                      - type: string
                        maxLength: 500
                      - type: 'null'
                  type:
                    type: string
                    minLength: 1
                    maxLength: 80
                required:
                  - city
                  - country
                  - id
                  - isPrimary
                  - label
                  - postalCode
                  - state
                  - street
                  - type
                additionalProperties: false
          required:
            - addresses
          additionalProperties: false
        familyName:
          anyOf:
            - type: string
              maxLength: 160
            - type: 'null'
        givenName:
          anyOf:
            - type: string
              maxLength: 160
            - type: 'null'
        id:
          $ref: '#/components/schemas/ArbolResourceId'
        summary:
          anyOf:
            - type: string
              maxLength: 4000
            - type: 'null'
        updatedAt:
          $ref: '#/components/schemas/IsoDatetime'
        facts:
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/Fact'
        identities:
          maxItems: 12
          type: array
          items:
            $ref: '#/components/schemas/ContactIdentity'
      required:
        - createdAt
        - details
        - familyName
        - givenName
        - id
        - summary
        - updatedAt
      additionalProperties: false
      title: Contact
    BadRequest:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: BAD_REQUEST
        status:
          const: 400
        message:
          type: string
        data:
          type: object
          properties:
            issues:
              maxItems: 20
              type: array
              items:
                type: object
                properties:
                  message:
                    type: string
                    maxLength: 500
                  path:
                    maxItems: 16
                    type: array
                    items:
                      anyOf:
                        - type: string
                          maxLength: 120
                        - type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                required:
                  - message
                additionalProperties: false
            truncated:
              type: boolean
          required:
            - issues
            - truncated
          additionalProperties: false
      required:
        - defined
        - inferable
        - code
        - status
        - message
        - data
    UndefinedError:
      type: object
      properties:
        defined:
          const: false
        inferable:
          type: boolean
        code:
          type: string
        status:
          type: number
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    TransportBadRequestError:
      additionalProperties: false
      properties:
        code:
          const: BAD_REQUEST
        data: {}
        defined:
          const: false
        inferable:
          const: false
        message:
          type: string
      required:
        - defined
        - inferable
        - code
        - message
      type: object
    Unauthorized:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: UNAUTHORIZED
        status:
          const: 401
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    Forbidden:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: FORBIDDEN
        status:
          const: 403
        message:
          type: string
        data:
          type: object
          properties:
            missingPermissions:
              maxItems: 10
              type: array
              items:
                $ref: '#/components/schemas/AuthPermission'
          required:
            - missingPermissions
          additionalProperties: false
      required:
        - defined
        - inferable
        - code
        - status
        - message
    NotFound:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: NOT_FOUND
        status:
          const: 404
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    Conflict3:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: CONFLICT
        status:
          const: 409
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    UnprocessableContent:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: UNPROCESSABLE_CONTENT
        status:
          const: 422
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    IsoDatetime:
      type: string
      format: date-time
      pattern: >-
        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
      description: ISO 8601 timestamp with an explicit UTC offset.
      examples:
        - '2026-08-29T14:30:00Z'
      title: ISO timestamp
    Fact:
      type: object
      properties:
        confidence:
          anyOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
        definition:
          type: object
          properties:
            description:
              anyOf:
                - type: string
                  maxLength: 2000
                - type: 'null'
            id:
              $ref: '#/components/schemas/ArbolResourceId'
            identifier:
              type: string
              minLength: 1
              maxLength: 100
            kind:
              $ref: '#/components/schemas/DefinitionKind'
            subjectKind:
              $ref: '#/components/schemas/DefinitionSubject'
            valueType:
              $ref: '#/components/schemas/DefinitionValueType'
          required:
            - description
            - id
            - identifier
            - kind
            - subjectKind
            - valueType
          additionalProperties: false
        id:
          $ref: '#/components/schemas/ArbolResourceId'
        observedAt:
          $ref: '#/components/schemas/IsoDatetime'
        reason:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
        recordedAt:
          $ref: '#/components/schemas/IsoDatetime'
        setBy:
          $ref: '#/components/schemas/FactActorKind'
        subject:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/ArbolResourceId'
            type:
              $ref: '#/components/schemas/DefinitionSubject'
          required:
            - id
            - type
          additionalProperties: false
        value:
          $ref: '#/components/schemas/FactValue'
        verificationStatus:
          $ref: '#/components/schemas/FactVerificationStatus'
      required:
        - confidence
        - definition
        - id
        - observedAt
        - reason
        - recordedAt
        - setBy
        - subject
        - value
        - verificationStatus
      additionalProperties: false
      description: >-
        Recorded immutable assertion with its Definition snapshot, provenance,
        and review state.
      title: Fact assertion
    ContactIdentity:
      type: object
      properties:
        address:
          type: string
          minLength: 1
          maxLength: 500
        id:
          $ref: '#/components/schemas/ArbolResourceId'
        isPrimary:
          type: boolean
        kind:
          $ref: '#/components/schemas/ContactIdentityKind'
        label:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
        verified:
          type: boolean
      required:
        - address
        - id
        - isPrimary
        - kind
        - label
        - verified
      additionalProperties: false
      description: >-
        Tenant-owned external address attached to a Contact; verification is
        explicit.
      title: Contact identity
    AuthPermission:
      type: string
      enum:
        - agent-evaluations:read
        - agent-evaluations:run
        - agent-evaluations:write
        - agents:read
        - agents:write
        - analytics:read
        - arbi:use
        - channels:read
        - channels:write
        - contacts:read
        - contacts:write
        - conversations:read
        - conversations:transcript
        - conversations:write
        - definitions:read
        - definitions:write
        - facts:read
        - facts:write
        - integrations:read
        - integrations:write
        - knowledge:read
        - knowledge:write
        - org:manage
        - org:use
      description: >-
        One permission from the closed Arbol API vocabulary accepted from a
        verified Auth0 token.
      examples:
        - agents:read
      title: API permission
    TransportPayloadTooLargeError:
      additionalProperties: false
      properties:
        code:
          const: PAYLOAD_TOO_LARGE
        data: {}
        defined:
          const: false
        inferable:
          const: false
        message:
          type: string
      required:
        - defined
        - inferable
        - code
        - message
      type: object
    TransportUnsupportedMediaTypeError:
      additionalProperties: false
      properties:
        code:
          const: UNSUPPORTED_MEDIA_TYPE
        data: {}
        defined:
          const: false
        inferable:
          const: false
        message:
          type: string
      required:
        - defined
        - inferable
        - code
        - message
      type: object
    DefinitionKind:
      type: string
      enum:
        - attribute
        - assessment
        - category
        - metric
      description: Semantic class of an organization-owned Definition.
      examples:
        - attribute
      title: Definition kind
    DefinitionSubject:
      type: string
      enum:
        - contact
        - conversation
      description: Resource type to which a Definition may be asserted.
      examples:
        - contact
      title: Definition subject
    DefinitionValueType:
      type: string
      enum:
        - text
        - number
        - boolean
        - date
        - option
      description: Validated value representation accepted by a Definition.
      examples:
        - option
      title: Definition value type
    FactActorKind:
      type: string
      enum:
        - ai
        - user
        - system
        - import
        - rule
      description: Origin category recorded for a Fact assertion.
      examples:
        - user
      title: Fact actor kind
    FactValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              const: text
            value:
              type: string
              maxLength: 8000
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: number
            value:
              type: number
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: boolean
            value:
              type: boolean
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: date
            value:
              type: string
              format: date
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            optionId:
              $ref: '#/components/schemas/ArbolResourceId'
            type:
              type: string
              const: option
            label:
              anyOf:
                - type: string
                  minLength: 1
                  maxLength: 160
                - type: 'null'
          required:
            - optionId
            - type
            - label
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: unset
          required:
            - type
          additionalProperties: false
      description: >-
        Typed value of an immutable Fact assertion; unset is an explicit
        tombstone.
      title: Fact value
    FactVerificationStatus:
      type: string
      enum:
        - unreviewed
        - confirmed
        - rejected
      description: Human review state of a Fact assertion.
      examples:
        - unreviewed
      title: Fact verification status
    ContactIdentityKind:
      type: string
      enum:
        - phone
        - email
        - telegram_user
        - slack_user
        - web
        - document
        - whatsapp_user
      description: Address namespace used to identify or reach a Contact.
      examples:
        - phone
      title: Contact identity kind
  headers:
    RequestId:
      description: >-
        Opaque request correlation identifier. Include it when contacting Arbol
        support.
      schema:
        type: string
        maxLength: 128
  responses:
    TransportPayloadTooLarge:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransportPayloadTooLargeError'
      description: The request body exceeds the API transport limit.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
    TransportUnsupportedMediaType:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransportUnsupportedMediaTypeError'
      description: The request media type is not supported.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  securitySchemes:
    userOAuth:
      description: >-
        Organization-scoped Auth0 user access token issued to an approved
        first-party client or exchanged by a trusted OBO resource server.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.getarbol.com/authorize
          scopes:
            agent-evaluations:read: Read Agent evaluation suites, runs, and results.
            agent-evaluations:run: Execute and cancel Agent evaluation runs.
            agent-evaluations:write: Create and update Agent evaluation suites.
            agents:read: Read Agents and their explicitly requested expansions.
            agents:write: Create, update, and delete Agents.
            analytics:read: Read organization analytics.
            arbi:use: Use the personal Arbi workspace.
            channels:read: Read Agent channels.
            channels:write: Create, update, authorize, and delete Agent channels.
            contacts:read: Read Contacts and their explicitly requested expansions.
            contacts:write: Create, update, merge, import, and delete Contacts.
            conversations:read: Read Conversation metadata.
            conversations:transcript: Read Conversation messages and media evidence.
            conversations:write: Create and process Conversations.
            definitions:read: Read Definitions and Definition usage.
            definitions:write: Create, update, and retire Definitions.
            facts:read: Read current and historical Facts.
            facts:write: Assert typed Facts.
            integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence.
            integrations:write: Authorize accounts and assign exact tool access.
            knowledge:read: Read Knowledge documents and search indexed content.
            knowledge:write: Create, index, update, and delete Knowledge documents.
            org:manage: Update the Organization and administer its members.
            org:use: Use Arbol as a member of the selected Auth0 Organization.
          tokenUrl: https://auth.getarbol.com/oauth/token
      type: oauth2
    machineOAuth:
      description: >-
        Organization-bound Auth0 client-credentials token. The client grant must
        contain every operation scope.
      flows:
        clientCredentials:
          scopes:
            agent-evaluations:read: Read Agent evaluation suites, runs, and results.
            agent-evaluations:run: Execute and cancel Agent evaluation runs.
            agent-evaluations:write: Create and update Agent evaluation suites.
            agents:read: Read Agents and their explicitly requested expansions.
            agents:write: Create, update, and delete Agents.
            analytics:read: Read organization analytics.
            channels:read: Read Agent channels.
            channels:write: Create, update, authorize, and delete Agent channels.
            contacts:read: Read Contacts and their explicitly requested expansions.
            contacts:write: Create, update, merge, import, and delete Contacts.
            conversations:read: Read Conversation metadata.
            conversations:transcript: Read Conversation messages and media evidence.
            conversations:write: Create and process Conversations.
            definitions:read: Read Definitions and Definition usage.
            definitions:write: Create, update, and retire Definitions.
            facts:read: Read current and historical Facts.
            facts:write: Assert typed Facts.
            integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence.
            integrations:write: Authorize accounts and assign exact tool access.
            knowledge:read: Read Knowledge documents and search indexed content.
            knowledge:write: Create, index, update, and delete Knowledge documents.
            org:manage: Update the Organization and administer its members.
          tokenUrl: https://auth.getarbol.com/oauth/token
      type: oauth2

````