Update contact - TalkToHumans

PATCH

https://api.talktohumans.app

/

v1

/

contacts

/

{contact_id}

curl --request PATCH \
  --url https://api.talktohumans.app/v1/contacts/{contact_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "42",
  "tags": {
    "add": [
      {
        "name": "Hot lead",
        "color": "red"
      }
    ],
    "remove": [
      "Old tag"
    ]
  }
}
'

{
  "data": {
    "contact": {
      "contact_id": "123",
      "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",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe/",
      "relationship_status": "connected",
      "work_email": "jane@acme.example",
      "phone": "+14155550123",
      "contact_enrichment": {
        "work_email": {
          "status": "found"
        },
        "phone": {
          "status": "found"
        }
      },
      "tags": [
        {
          "name": "Hot lead",
          "color": "red"
        }
      ],
      "notes": [
        {
          "note_id": "0b7e4c2a-5d1f-4a8e-9c3b-6f2d1e0a9b8c",
          "content": "Follow up next week",
          "created_at": "2026-06-24T09:15:00Z"
        }
      ],
      "app_url": "https://app.talktohumans.app/contacts",
      "Deal stage": "Qualified",
      "Lead score": 91,
      "Next follow-up": "2026-07-01",
      "VIP": true
    }
  }
}

Authorizations

Authorization

string

header

required

Pass API key as Authorization: Bearer <api_key>.

Path Parameters

contact_id

string

required

Contact ID returned by GET /v1/contacts.

Pattern: ^[1-9][0-9]*$

Body

application/json

Contact update payload. Known system keys, including tags and notes, are documented below. Any additional top-level key is treated as a registered custom field key. Provide at least one of tags, notes, or a custom field key.

account_id

string

LinkedIn account ID returned by GET /v1/accounts. Required when the contact exists under multiple LinkedIn accounts.

Pattern: ^[1-9][0-9]*$

tags

object

Use set for exact replacement, or add/remove for incremental updates. set cannot be combined with add or remove.

Show child attributes

notes

object

Use set for exact replacement, or add/remove for incremental updates. set cannot be combined with add or remove. A contact or company can have at most 20 notes.

Show child attributes

{key}

Value for a registered custom field key. Use null to clear. Date fields must use YYYY-MM-DD strings.

Response

Contact updated.

data

object

required

Show child attributes

curl --request PATCH \
  --url https://api.talktohumans.app/v1/contacts/{contact_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "42",
  "tags": {
    "add": [
      {
        "name": "Hot lead",
        "color": "red"
      }
    ],
    "remove": [
      "Old tag"
    ]
  }
}
'

{
  "data": {
    "contact": {
      "contact_id": "123",
      "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",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe/",
      "relationship_status": "connected",
      "work_email": "jane@acme.example",
      "phone": "+14155550123",
      "contact_enrichment": {
        "work_email": {
          "status": "found"
        },
        "phone": {
          "status": "found"
        }
      },
      "tags": [
        {
          "name": "Hot lead",
          "color": "red"
        }
      ],
      "notes": [
        {
          "note_id": "0b7e4c2a-5d1f-4a8e-9c3b-6f2d1e0a9b8c",
          "content": "Follow up next week",
          "created_at": "2026-06-24T09:15:00Z"
        }
      ],
      "app_url": "https://app.talktohumans.app/contacts",
      "Deal stage": "Qualified",
      "Lead score": 91,
      "Next follow-up": "2026-07-01",
      "VIP": true
    }
  }
}