Skip to main content
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": {
      "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"
    }
  }
}

Authorizations

​
Authorization
string
header
required

Pass your 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 are documented below. Any additional top-level key is treated as a registered 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.

​
notes_json
string | null

Valid JSON text to store as account-scoped notes. Use null or an empty string to clear notes.

​
{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