ReplySparrow Contacts
Create a new contact
Creates a contact in the workspace and emits a contact.created event. Needs the contacts:write scope.
first_name, last_name and linkedin_url are required (full_name alone is also accepted in place of the two names). With list_id the contact is added to that list, and with agent_id it is attached to that lead source agent and scored against its ICP.
A person you have excluded (see Excluded Contacts, e.g. a contact you deleted) cannot be created again: when the linkedin_url or email matches an exclusion the call fails with 409 contact_already_excluded. Delete the exclusion first to add them back.
https://app.replysparrow.com/api/v1/contactsAuthorizations
Body
application/jsonContact data to create. first_name, last_name and linkedin_url are required, all other fields are optional.
Full name. Optional: built from first_name and last_name when omitted; may replace them
Example: "John Doe"
LinkedIn About section
LinkedIn company page URL
Example: "https://www.linkedin.com/company/techcorp"
What the company does
LinkedIn member id of the profile (the ACoAA... id or its URN), when you have it
Example: "ACoAABcwGZ0BPKyEbC2o13Qq7MhrAaD"
Profile picture URL
Internal notes about the contact
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
With agent_id: accept the lead as is, so the agent hands it to the campaign on its next pass without waiting for an ICP score
Workspace member who owns the contact (user id)
Lead source agent to attach the contact to; it is then scored against that agent's ICP
List to add the contact to. Useful to put a contact straight into a campaign that reaches out to that list
Response
application/jsonContact successfully created
Workspace the contact belongs to
First name
Last name
Full name (built from first_name and last_name when not sent)
LinkedIn headline
LinkedIn About section
Current job title
Seniority level
Months in the current role
LinkedIn profile URL
LinkedIn member id (URN)
Profile picture URL
LinkedIn connection degree with your seat (1, 2 or 3)
Location of the contact
City
Country
IANA time zone
Current company name
Linked company record
Employee count of the current company
Industry of the current company
Headquarters of the current company
LinkedIn company page URL
Company logo URL
What the company does
Personal or company website
Dates of the current position
Primary email address
Result of the last email check: valid, invalid, risky, catch_all or unknown
When the email was last verified
1 when the email domain accepts every address
Primary phone number
Buying-signal score from the contact's signals (0-100)
ICP fit score (0-100), set once the contact is scored
ICP verdict, e.g. fit or not_fit
Why the contact does or does not fit the ICP
How sure the ICP verdict is: high, medium or low
Combined lead score (0-100): fit, signals, recency and relevance
When the contact was last scored
Where the contact came from, e.g. api, csv, agent
Lead source agent that sourced the contact
Where the contact is in its agent's pipeline: new, qualified, enrolled, skipped (rejected), ...
Why the contact was rejected or skipped
1 when someone added the contact by hand
Workspace member who owns the contact
Internal notes
When the LinkedIn invitation was sent
When the LinkedIn connection was accepted
Last LinkedIn message sent
Last InMail sent
Last reply on LinkedIn
Last reply by email
How the last reply was classified, e.g. interested, not_interested, out_of_office
When the profile was last enriched
Creation timestamp
Public LinkedIn identifier taken from linkedin_url, e.g. johndoe
Skills from the LinkedIn profile
An email to the contact bounced, or its address was found invalid
The contact unsubscribed from your emails
The person is on your blocklist
The contact's company is on your blocklist
The contact has an email that was found or verified
The contact has a phone number
An email lookup is running for the contact
A phone lookup is running for the contact
The contact's agent accepted it, so its campaign can reach out
The contact is or was enrolled in a campaign
Where the contact stands overall
Available options: newin_campaignfinishedrepliedrejected
When this contact was rejected (null when it is not rejected)
User who rejected this contact
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
Free-text reason when other was submitted with text
Intent or activity description: the title of the contact's most recent signal
Intent type of the most recent signal, e.g. job_change, funding or custom
Keyword of the most recent signal (its metadata.keyword), e.g. demo_booked
The contact's progress in each campaign and channel
The contact's signals, newest first (up to 50)
Workspace custom field values, by field key
The lead source agent the contact belongs to, as Get a source agent returns it
Lists the contact belongs to
curl --request POST \ --url https://app.replysparrow.com/api/v1/contacts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "first_name": "John", "last_name": "Doe", "linkedin_url": "https://www.linkedin.com/in/johndoe", "headline": "Head of Sales at Tech Corp", "title": "Head of Sales", "location": "New York, NY", "company": "Tech Corp", "company_size": 120, "company_industry": "Software Development", "email": "john@techcorp.com", "phone": "+1234567890"}'{ "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" } ] } ]}