Contacts

Update a contact

Updates the fields you send and leaves the others unchanged (send null to clear a field; full_name and linkedin_url cannot be cleared). Needs the contacts:write scope.

ready_for_campaign is mainly used for review mode campaigns: true accepts the lead (agent_status becomes qualified), so its lead source agent hands it to the campaign on its next pass without manual review. It needs an agent: the contact's own, or one sent as agent_id in the same call. false takes an accepted lead that has not started a campaign back to review (agent_status new).

intent describes what the contact did (e.g. "Liked our post about outbound") and is saved as a new custom signal on the contact, as with Add a signal to a contact.

patchhttps://app.replysparrow.com/api/v1/contacts/{id}

Authorizations

Authorizationstringheaderrequired

Your API key from Settings → API, sent as Bearer <token>.

Path Parameters

idstringrequired

Contact id

Body

application/json

first_namestring

First name of the contact

Example: "John"

last_namestring

Last name of the contact

Example: "Doe"

headlinestring

LinkedIn headline

Example: "Head of Sales at Tech Corp"

summarystring

LinkedIn About section

titlestring

Current job title

Example: "Software Engineer"

position_datesstring

Dates of the current position, as LinkedIn shows them

Example: "2020 - Present"

senioritystring

Seniority level, e.g. senior, director, vp, c_suite

Example: "director"

locationstring

Location of the contact

Example: "New York, NY"

citystring

City

Example: "New York"

countrystring

Country

Example: "United States"

time_zonestring

IANA time zone, used to send at a good local time

Example: "America/New_York"

companystring

Current company name

Example: "Tech Corp"

company_sizenumber

Employee count of the current company

Example: 120

company_industrystring

Industry of the current company

Example: "Software Development"

company_linkedin_urlstring

LinkedIn company page URL

Example: "https://www.linkedin.com/company/techcorp"

company_descriptionstring

What the company does

websitestring

Personal or company website

Example: "https://johndoe.com"

profile_image_urlstring

Profile picture URL

emailstring

Primary email address

Example: "john@techcorp.com"

phonestring

Primary phone number

Example: "+1234567890"

notesstring

Internal notes about the contact

owner_idstring

Workspace member who owns the contact (user id)

agent_idstring

Lead source agent to attach the contact to; it is then scored against that agent's ICP

full_namestring

Full name

Example: "John Doe"

linkedin_urlstring

LinkedIn profile URL

Example: "https://www.linkedin.com/in/johndoe"

intentstring

What the contact did that shows interest, e.g. "Liked our post about outbound". Saved as a custom signal on the contact, which raises its intent score

ready_for_campaignboolean

Mainly used for review mode campaigns: true accepts the lead (it needs a lead source agent, already set or sent as agent_id), so its agent hands it to the campaign on its next pass without waiting for an ICP score. false takes an accepted lead back to review (agent_status new)

Response

application/json

Contact successfully updated

idstringrequired

Unique identifier of the contact

Example: "8f1c2c3e-5b7a-4a51-9d0e-2b6f8f6d9c11"

workspace_idstringrequired

Workspace the contact belongs to

first_namestringrequired

First name

last_namestringrequired

Last name

full_namestringrequired

Full name (built from first_name and last_name when not sent)

headlinestringrequired

LinkedIn headline

summarystringrequired

LinkedIn About section

titlestringrequired

Current job title

senioritystringrequired

Seniority level

tenure_monthsnumberrequired

Months in the current role

linkedin_urlstringrequired

LinkedIn profile URL

sales_nav_urlstringrequired

Sales Navigator profile URL

linkedin_member_urnstringrequired

LinkedIn member id (URN)

profile_image_urlstringrequired

Profile picture URL

degreenumberrequired

LinkedIn connection degree with your seat (1, 2 or 3)

locationstringrequired

Location of the contact

citystringrequired

City

countrystringrequired

Country

time_zonestringrequired

IANA time zone

companystringrequired

Current company name

company_idstringrequired

Linked company record

company_sizenumberrequired

Employee count of the current company

company_industrystringrequired

Industry of the current company

company_locationstringrequired

Headquarters of the current company

company_linkedin_urlstringrequired

LinkedIn company page URL

company_logo_urlstringrequired

Company logo URL

company_descriptionstringrequired

What the company does

websitestringrequired

Personal or company website

position_datesstringrequired

Dates of the current position

emailstringrequired

Primary email address

email_statusstringrequired

Result of the last email check: valid, invalid, risky, catch_all or unknown

email_verified_atstringrequired

When the email was last verified

email_domain_catchallnumberrequired

1 when the email domain accepts every address

phonestringrequired

Primary phone number

intent_scorenumberrequired

Buying-signal score from the contact's signals (0-100)

fit_scorenumberrequired

ICP fit score (0-100), set once the contact is scored

fit_verdictstringrequired

ICP verdict, e.g. fit or not_fit

fit_reasonstringrequired

Why the contact does or does not fit the ICP

fit_confidencestringrequired

How sure the ICP verdict is: high, medium or low

lead_scorenumberrequired

Combined lead score (0-100): fit, signals, recency and relevance

scored_atstringrequired

When the contact was last scored

lead_sourcestringrequired

Where the contact came from, e.g. api, csv, agent

agent_idstringrequired

Lead source agent that sourced the contact

agent_statusstringrequired

Where the contact is in its agent's pipeline: new, qualified, enrolled, skipped (rejected), ...

skip_reasonstringrequired

Why the contact was rejected or skipped

hand_pickednumberrequired

1 when someone added the contact by hand

owner_idstringrequired

Workspace member who owns the contact

notesstringrequired

Internal notes

connection_requested_atstringrequired

When the LinkedIn invitation was sent

connected_atstringrequired

When the LinkedIn connection was accepted

message_sent_atstringrequired

Last LinkedIn message sent

inmail_sent_atstringrequired

Last InMail sent

last_replied_atstringrequired

Last reply on LinkedIn

email_replied_atstringrequired

Last reply by email

reply_kindstringrequired

How the last reply was classified, e.g. interested, not_interested, out_of_office

enriched_atstringrequired

When the profile was last enriched

created_atstringrequired

Creation timestamp

linkedin_identifierstringrequired

Public LinkedIn identifier taken from linkedin_url, e.g. johndoe

skillsstring[]required

Skills from the LinkedIn profile

bouncedbooleanrequired

An email to the contact bounced, or its address was found invalid

unsubscribedbooleanrequired

The contact unsubscribed from your emails

blockedbooleanrequired

The person is on your blocklist

company_blockedbooleanrequired

The contact's company is on your blocklist

email_enrichedbooleanrequired

The contact has an email that was found or verified

phone_enrichedbooleanrequired

The contact has a phone number

enriching_emailbooleanrequired

An email lookup is running for the contact

enriching_phonebooleanrequired

A phone lookup is running for the contact

ready_for_campaignbooleanrequired

The contact's agent accepted it, so its campaign can reach out

has_started_campaignbooleanrequired

The contact is or was enrolled in a campaign

stateenum<string>required

Where the contact stands overall

Available options: newin_campaignfinishedrepliedrejected

rejected_atstringrequired

When this contact was rejected (null when it is not rejected)

rejected_by_user_idstringrequired

User who rejected this contact

rejection_reasonenum<string>required

Stable rejection reason code

Available options: company_competitorcompany_wrong_industry_or_typecompany_wrong_sizecompany_wrong_locationcontact_wrong_title_or_functioncontact_wrong_senioritycontact_known_or_duplicatedata_incorrect_or_outdatedsignal_not_relevantothernull

rejection_reason_textstringrequired

Free-text reason when other was submitted with text

intentstringrequired

Intent or activity description: the title of the contact's most recent signal

intent_typestringrequired

Intent type of the most recent signal, e.g. job_change, funding or custom

intent_keywordstringrequired

Keyword of the most recent signal (its metadata.keyword), e.g. demo_booked

campaign_statusobject[]required

The contact's progress in each campaign and channel

signalsobject[]required

The contact's signals, newest first (up to 50)

custom_fieldsobjectrequired

Workspace custom field values, by field key

agentobjectrequired

The lead source agent the contact belongs to, as Get a source agent returns it

listsobject[]required

Lists the contact belongs to

Ctrl+I

Update a contact

curl --request PATCH \  --url https://app.replysparrow.com/api/v1/contacts/string \  --header 'Authorization: Bearer <token>' \  --header 'Content-Type: application/json' \  --data '{  "title": "CTO",  "company": "Tech Corp",  "notes": "Met at SaaStr",  "ready_for_campaign": true}'

{  "id": "8f1c2c3e-5b7a-4a51-9d0e-2b6f8f6d9c11",  "workspace_id": "ws_123",  "first_name": "Ada",  "last_name": "Lovelace",  "full_name": "Ada Lovelace",  "headline": "CTO at Analytical Engines",  "summary": null,  "title": "CTO",  "seniority": null,  "tenure_months": null,  "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",  "sales_nav_url": null,  "linkedin_member_urn": null,  "profile_image_url": null,  "degree": null,  "location": "London, UK",  "city": null,  "country": null,  "time_zone": null,  "company": "Analytical Engines",  "company_id": null,  "company_size": 120,  "company_industry": "Software Development",  "company_location": null,  "company_linkedin_url": null,  "company_logo_url": null,  "company_description": null,  "website": null,  "position_dates": "2023 - Present",  "email": "ada@example.com",  "email_status": "valid",  "email_verified_at": null,  "email_domain_catchall": null,  "phone": "+441234567890",  "intent_score": 25,  "fit_score": 88,  "fit_verdict": "fit",  "fit_reason": null,  "fit_confidence": null,  "lead_score": 82,  "scored_at": null,  "lead_source": "api",  "agent_id": null,  "agent_status": "qualified",  "skip_reason": null,  "hand_picked": 0,  "owner_id": null,  "notes": null,  "connection_requested_at": null,  "connected_at": null,  "message_sent_at": null,  "inmail_sent_at": null,  "last_replied_at": null,  "email_replied_at": null,  "reply_kind": null,  "enriched_at": null,  "created_at": "2026-10-01 09:12:44",  "linkedin_identifier": "ada-lovelace",  "skills": [    "Mathematics",    "Engineering"  ],  "bounced": false,  "unsubscribed": false,  "blocked": false,  "company_blocked": false,  "email_enriched": true,  "phone_enriched": true,  "enriching_email": false,  "enriching_phone": false,  "ready_for_campaign": true,  "has_started_campaign": true,  "state": "in_campaign",  "rejected_at": null,  "rejected_by_user_id": null,  "rejection_reason": null,  "rejection_reason_text": null,  "intent": "Became CTO at Analytical Engines",  "intent_type": "job_change",  "intent_keyword": null,  "campaign_status": [    {      "campaign_id": "a3f1c2d4-0000-4000-8000-000000000001",      "campaign_name": "Q4 founders",      "track": "linkedin",      "state": "in_progress",      "current_step": 2,      "next_step_at": "2026-10-26 09:00:00"    }  ],  "signals": [    {      "id": "c7e0e0a2-2f4b-4c1e-9d55-0b9a4e3f1a10",      "contact_id": "8f1c2c3e-5b7a-4a51-9d0e-2b6f8f6d9c11",      "type": "job_change",      "title": "Became CTO at Analytical Engines",      "description": null,      "score": 25,      "source": "linkedin",      "source_url": null,      "occurred_at": "2026-09-28T00:00:00.000Z",      "metadata": {},      "created_at": "2026-09-28T08:00:00.000Z"    }  ],  "custom_fields": {    "favorite_tool": "Notion"  },  "agent": {    "id": "5b0f3c2e-8a8e-4bd1-9a51-6f1f3c0f2a10",    "name": "VP Sales in US SaaS",    "target_job_titles": [      "VP Sales",      "Head of Sales"    ],    "target_industries": [      "Software Development"    ],    "target_company_sizes": [      "51-200",      "201-500"    ],    "target_locations": [      "United States"    ],    "target_company_types": [],    "ignored_companies": [      "Globex"    ],    "mandatory_keywords": [],    "exclude_service_providers": true,    "skip_icp_filter": false,    "signals": [      {        "id": "8e2d…",        "type": "competitor_engagement",        "values": [          "https://www.linkedin.com/company/globex/"        ],        "enabled": true      }    ],    "paused": false,    "status": "active",    "min_lead_score": 70,    "list_id": "c1a4…",    "last_run": null,    "last_error": null,    "created_at": "2026-10-24T09:12:44.000Z",    "updated_at": "2026-10-24T09:12:44.000Z"  },  "lists": [    {      "id": "list_1",      "name": "Q4 targets",      "campaigns": [        {          "id": "5b0c6c1e-8a43-4f7e-9d7d-1f8a2b3c4d5e",          "name": "Q4 founders",          "active": false,          "channel": "linkedin",          "status": "draft",          "goal": "conversations",          "tone": "professional",          "language": null,          "booking_url": null,          "exclude_first_degree": true,          "split_messages": false,          "skip_invitation_after_days": 7,          "linkedin_account_id": "acc_123",          "email_account_id": null,          "linkedin_account_ids": [            "acc_123"          ],          "email_account_ids": [],          "list_id": "9f8e7d6c-0000-4000-8000-000000000001",          "list_ids": [            "9f8e7d6c-0000-4000-8000-000000000002"          ],          "workflow_id": "wf_123",          "steps": [            {              "id": "st_1",              "track": "linkedin",              "order": 1,              "type": "connect",              "delay_days": null,              "message": null,              "connect_note": null,              "email_subject": null,              "email_body": null,              "ai": true            },            {              "id": "st_2",              "track": "linkedin",              "order": 2,              "type": "delay",              "delay_days": 1,              "message": null,              "connect_note": null,              "email_subject": null,              "email_body": null,              "ai": false            },            {              "id": "st_3",              "track": "linkedin",              "order": 3,              "type": "message",              "delay_days": null,              "message": "Hi {{first_name}}, thanks for connecting!",              "connect_note": null,              "email_subject": null,              "email_body": null,              "ai": false            }          ],          "created_at": "2026-10-24T09:12:44.000Z",          "updated_at": "2026-10-24T09:12:44.000Z"        }      ]    }  ]}