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

# Update contact

> Use this endpoint to update a specific contact.




## OpenAPI

````yaml /openapi.yaml patch /v1/contacts/{contact_id}
openapi: 3.0.3
info:
  title: TalkToHumans Public API
  version: 1.0.0
  license:
    name: Proprietary
  description: >
    Read and organize the LinkedIn workspace data your team already manages in
    TalkToHumans: accounts, people, tags, notes, sequence state, conversations,
    and views.
servers:
  - url: https://api.talktohumans.app
    description: TalkToHumans API
security:
  - bearerAuth: []
tags:
  - name: Organization
    description: Workspace details for the current API key.
  - name: LinkedIn
    description: >-
      Accounts, contacts, companies, and conversations already synced into
      TalkToHumans.
  - name: Enrich
    description: Profile enrichment for LinkedIn people and companies.
  - name: Views
    description: Saved TalkToHumans views and lists.
paths:
  /v1/contacts/{contact_id}:
    patch:
      tags:
        - LinkedIn
      summary: Update contact
      description: |
        Use this endpoint to update a specific contact.
      operationId: updateContact
      parameters:
        - name: contact_id
          in: path
          required: true
          description: Contact ID returned by `GET /v1/contacts`.
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactRequest'
            examples:
              addRemoveTags:
                summary: Add and remove tags
                value:
                  account_id: '42'
                  tags:
                    add:
                      - name: Hot lead
                        color: red
                    remove:
                      - Old tag
              setTags:
                summary: Replace workspace tags
                value:
                  account_id: '42'
                  tags:
                    set:
                      - name: Customer
                        color: green
              clearNotes:
                summary: Clear notes
                value:
                  account_id: '42'
                  notes_json: null
              setCustomFields:
                summary: Set custom fields
                description: Each custom field key is the field's registered name.
                value:
                  account_id: '42'
                  Deal stage: Qualified
                  Lead score: 91
                  Next follow-up: '2026-07-01'
                  VIP: true
              clearCustomField:
                summary: Clear a custom field
                value:
                  account_id: '42'
                  Next follow-up: null
      responses:
        '200':
          description: Contact updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateContactEnvelope'
              example:
                data:
                  contact:
                    account_relationship_id: '1042'
                    contact_id: '123'
                    provider_participant_id: urn:li:fsd_profile:abc
                    public_identifier: jane-doe
                    account:
                      account_id: '42'
                      display_name: Jane Doe
                      provider_account_id: ACoAA000000
                      owner_user_id: '7'
                    name: Jane Doe
                    first_name: Jane
                    last_name: Doe
                    headline: Founder at Acme
                    primary_role_title: Founder
                    primary_company_name: Acme
                    work_email: jane@acme.example
                    phone: '+14155550123'
                    linkedin_url: https://www.linkedin.com/in/jane-doe/
                    avatar_url: >-
                      https://media.licdn.com/dms/image/example/profile-displayphoto.jpg
                    background_cover_url: >-
                      https://media.licdn.com/dms/image/example/profile-cover.jpg
                    relationship_status: connected
                    Deal stage: Qualified
                    Lead score: 91
                    Next follow-up: '2026-07-01'
                    VIP: true
                    tags:
                      - name: Hot lead
                        color: red
                    notes_json: '[{"id":"n1","content":"Follow up next week"}]'
                    languages:
                      - language: English
                    experiences:
                      - experience_id: exp_2f8c1b
                        company_participant_id: linkedin:participant:urn:li:fsd_company:123
                        company_provider_participant_id: urn:li:fsd_company:123
                        company_name: Acme
                        title: Founder
                        employment_type: Full-time
                        location: San Francisco Bay Area
                        start_at: 2021-01
                        is_current: true
                        description: Building business software for sales teams.
                    educations:
                      - education_id: edu_91ac42
                        school_participant_id: linkedin:participant:urn:li:fsd_company:987
                        school_provider_participant_id: urn:li:fsd_company:987
                        school_name: Stanford University
                        degree: MBA
                        field_of_study: Business Administration
                        start_at: '2014'
                        end_at: '2016'
                    locations:
                      - linkedin_text: San Francisco Bay Area
                        display_text: San Francisco, California, United States
                        country_code: US
                        region_code: US-CA
                        country: United States
                        country_full: United States
                        state: California
                        city: San Francisco
                        geographic_area: San Francisco Bay Area
                        is_primary: true
                        is_headquarter: false
                    app_url: https://app.talktohumans.app/contacts
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    UpdateContactRequest:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CustomFieldValueInput'
      description: >
        Contact update payload. Known system keys are documented below. Any
        additional top-level key is treated

        as a registered custom field key.
      minProperties: 1
      properties:
        account_id:
          type: string
          description: >-
            LinkedIn account ID returned by `GET /v1/accounts`. Required when
            the contact exists under multiple LinkedIn accounts.
          pattern: ^[1-9][0-9]*$
        tags:
          $ref: '#/components/schemas/ContactTagsPatch'
        notes_json:
          type: string
          nullable: true
          description: >-
            Valid JSON text to store as account-scoped notes. Use null or an
            empty string to clear notes.
    UpdateContactEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/UpdateContactResponse'
    CustomFieldValueInput:
      nullable: true
      description: >-
        Value for a registered custom field key. Use null to clear. Date fields
        must use `YYYY-MM-DD` strings.
      oneOf:
        - type: string
        - type: number
        - type: boolean
    ContactTagsPatch:
      type: object
      additionalProperties: false
      description: >-
        Use `set` for exact replacement, or `add`/`remove` for incremental
        updates. `set` cannot be combined with `add` or `remove`.
      properties:
        add:
          type: array
          items:
            $ref: '#/components/schemas/ContactTagInput'
        remove:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
        set:
          type: array
          items:
            $ref: '#/components/schemas/ContactTagInput'
    UpdateContactResponse:
      type: object
      additionalProperties: false
      required:
        - contact
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
    Error:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - unauthorized
            - forbidden
            - not_found
            - bad_request
            - internal_error
            - conflict
            - rate_limit_exceeded
            - billing_payment_failed
            - billing_subscription_incomplete
            - billing_subscription_expired
            - billing_grace_period
            - billing_feature_not_available
            - billing_insufficient_credits
            - billing_invalid
            - upstream_error
        message:
          type: string
          description: Human-readable error message.
        debug:
          type: string
          description: Development-only debug details.
    ContactTagInput:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        color:
          type: string
          description: >-
            Supported values are green, orange, blue, red, purple, yellow, pink,
            and grey. Defaults to blue when omitted or unsupported.
    Contact:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CustomFieldValue'
      description: >
        LinkedIn contact. Registered custom field values may appear as
        additional top-level properties using

        each custom field's `key`, alongside the system fields documented below.
      required:
        - account_relationship_id
        - contact_id
        - provider_participant_id
        - account
        - name
        - relationship_status
        - tags
        - languages
        - experiences
        - educations
        - locations
        - app_url
      properties:
        account_relationship_id:
          type: string
        contact_id:
          type: string
          description: TalkToHumans contact ID.
        provider_participant_id:
          type: string
          description: LinkedIn participant ID.
        public_identifier:
          type: string
        account:
          $ref: '#/components/schemas/AccountSummary'
        name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        headline:
          type: string
        primary_role_title:
          type: string
        primary_company_name:
          type: string
        work_email:
          type: string
          description: Work email when email enrichment was found for this organization.
        phone:
          type: string
          description: Phone number when phone enrichment was found for this organization.
        linkedin_url:
          type: string
          format: uri
        avatar_url:
          type: string
          format: uri
        background_cover_url:
          type: string
          format: uri
        about:
          type: string
        profile_action_label:
          type: string
        profile_action_url:
          type: string
          format: uri
        follower_count:
          type: integer
          nullable: true
        connections_count:
          type: integer
          nullable: true
        relationship_status:
          $ref: '#/components/schemas/RelationshipStatus'
        connection_invitation:
          $ref: '#/components/schemas/ConnectionInvitation'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/APITag'
        notes_json:
          type: string
          description: Notes stored as JSON text.
        languages:
          type: array
          items:
            $ref: '#/components/schemas/Language'
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/Experience'
        educations:
          type: array
          items:
            $ref: '#/components/schemas/Education'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        company:
          $ref: '#/components/schemas/Company'
        last_interaction_at:
          type: string
          format: date-time
          nullable: true
        sequence:
          $ref: '#/components/schemas/Sequence'
        app_url:
          type: string
          format: uri
    CustomFieldValue:
      nullable: true
      description: >-
        Custom field value. Text fields return strings, number fields return
        numbers, boolean fields return booleans, and date fields return
        `YYYY-MM-DD` strings. Null appears only when a value is explicitly
        cleared or absent in a write response.
      oneOf:
        - type: string
        - type: number
        - type: boolean
    AccountSummary:
      type: object
      additionalProperties: false
      required:
        - account_id
        - display_name
        - provider_account_id
        - owner_user_id
      properties:
        account_id:
          type: string
          description: TalkToHumans account ID.
        display_name:
          type: string
        provider_account_id:
          type: string
          description: LinkedIn provider account ID.
        owner_user_id:
          type: string
          description: TalkToHumans user ID that owns the account.
    RelationshipStatus:
      type: string
      enum:
        - connected
        - not_connected
        - unknown
    ConnectionInvitation:
      type: object
      additionalProperties: false
      nullable: true
      required:
        - status
        - direction
      properties:
        status:
          type: string
          enum:
            - pending
        direction:
          type: string
          enum:
            - incoming
            - outgoing
            - unknown
        invite_id:
          type: string
        invite_state:
          type: string
        invite_type:
          type: string
        received_at:
          type: string
          format: date-time
          nullable: true
    APITag:
      type: object
      additionalProperties: false
      required:
        - name
        - color
      properties:
        name:
          type: string
        color:
          type: string
          enum:
            - green
            - orange
            - blue
            - red
            - purple
            - yellow
            - pink
            - grey
    Language:
      type: object
      additionalProperties: false
      required:
        - language
      properties:
        language:
          type: string
    Experience:
      type: object
      additionalProperties: false
      required:
        - experience_id
        - is_current
      properties:
        experience_id:
          type: string
        company_participant_id:
          type: string
        company_provider_participant_id:
          type: string
        company_name:
          type: string
        title:
          type: string
        employment_type:
          type: string
        location:
          type: string
        start_at:
          type: string
        end_at:
          type: string
        is_current:
          type: boolean
        description:
          type: string
    Education:
      type: object
      additionalProperties: false
      required:
        - education_id
      properties:
        education_id:
          type: string
        school_participant_id:
          type: string
        school_provider_participant_id:
          type: string
        school_name:
          type: string
        degree:
          type: string
        field_of_study:
          type: string
        start_at:
          type: string
        end_at:
          type: string
        description:
          type: string
    Location:
      type: object
      additionalProperties: false
      required:
        - is_primary
        - is_headquarter
      properties:
        linkedin_text:
          type: string
        display_text:
          type: string
        country_code:
          type: string
        region_code:
          type: string
        country:
          type: string
        country_full:
          type: string
        state:
          type: string
        city:
          type: string
        geographic_area:
          type: string
        is_primary:
          type: boolean
        is_headquarter:
          type: boolean
    Company:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CustomFieldValue'
      description: |
        A company.
      nullable: true
      required:
        - company_id
        - provider_participant_id
        - name
        - industries
        - locations
      properties:
        company_id:
          type: string
        provider_participant_id:
          type: string
        public_identifier:
          type: string
        name:
          type: string
        headline:
          type: string
        linkedin_url:
          type: string
          format: uri
        avatar_url:
          type: string
          format: uri
        background_cover_url:
          type: string
          format: uri
        headcount:
          type: string
        employee_count:
          type: integer
          nullable: true
        founding_date:
          type: string
        website_url:
          type: string
          format: uri
        follower_count:
          type: integer
          nullable: true
        about:
          type: string
        notes_json:
          type: string
          description: Notes stored as JSON text.
        industries:
          type: array
          items:
            $ref: '#/components/schemas/Industry'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        tags:
          type: array
          description: >-
            Workspace tags on the company. Present on the dedicated company
            resource.
          items:
            $ref: '#/components/schemas/APITag'
    Sequence:
      type: object
      additionalProperties: false
      nullable: true
      required:
        - sequence_id
        - status
        - stop_if_person_replies
        - steps
      properties:
        sequence_id:
          type: string
        status:
          type: string
        stop_if_person_replies:
          type: boolean
        reply_guard_after:
          type: string
          format: date-time
          nullable: true
        next_step_id:
          type: string
        next_step_scheduled_for:
          type: string
          format: date-time
          nullable: true
        steps:
          type: array
          items:
            $ref: '#/components/schemas/SequenceStep'
    Industry:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        title:
          type: string
        industry_urn:
          type: string
        provider_industry_id:
          type: string
        hierarchy:
          type: string
    SequenceStep:
      type: object
      additionalProperties: false
      required:
        - step_id
        - step_type
        - trigger_type
        - position
        - message_mode
        - state
      properties:
        step_id:
          type: string
        template_run_public_id:
          type: string
        step_type:
          type: string
        trigger_type:
          type: string
        position:
          type: integer
          format: int32
        scheduled_for:
          type: string
          format: date-time
          nullable: true
        message_mode:
          type: string
        state:
          type: string
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: bad_request
            message: Invalid request parameters
    Unauthorized:
      description: Missing, malformed, or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingAuthorization:
              value:
                code: unauthorized
                message: Authorization header is required
            invalidAuthorizationFormat:
              value:
                code: unauthorized
                message: Authorization header must use Bearer scheme
            invalidAPIKey:
              value:
                code: unauthorized
                message: Invalid API key
    Forbidden:
      description: >-
        API access is not enabled for the workspace, or the credential cannot
        access the requested workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              value:
                code: forbidden
                message: you don't have access to this organization
            featureUnavailable:
              value:
                code: billing_feature_not_available
                message: >-
                  Feature 'TalkToHumansAPI' is not available in your current
                  plan
            insufficientCredits:
              value:
                code: billing_insufficient_credits
                message: Insufficient credits
    RateLimited:
      description: >-
        Rate limit exceeded. Public routes allow 50 requests per 10 seconds per
        IP and endpoint.
      headers:
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limit_exceeded
            message: Rate limit exceeded
    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: internal_error
            message: An internal error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as `Authorization: Bearer <api_key>`.'

````