Contact API

Interfaces to manage contacts

A contact is a person or business prospect that you are reaching out to. You can add contacts to campaigns and send them emails, LinkedIn messages, or Twitter actions.

ℹ️

V2 API Recommended

V2 API provides standardized responses and better error handling. See endpoint comparisons below.

Create Contact

Create a new contact in a campaign.

Important: At least one of email, linkedin_url, or twitter must be provided.

V2 API (Recommended)

bash

curl -X POST 'https://api.supersend.io/v2/contacts' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Joe", "last_name": "Paul", "email": "joe.paul@example.com", "company_name": "ABC Corp", "title": "Manager", "phone": "+1-534-634-5346", "city": "Raleigh", "state": "NC", "country": "United States", "custom": { "department": "Sales" }, "TeamId": "your-team-id", "CampaignId": "your-campaign-id" }'

# Response (201 Created) { "success": true, "data": { "id": "e8048d7f-3b04-4d6a-b73f-a400b514f626", "email": "joe.paul@example.com", "first_name": "Joe", "last_name": "Paul", "company_name": "ABC Corp", "title": "Manager", "phone": "+1-534-634-5346", "city": "Raleigh", "state": "NC", "country": "United States", "custom": { "department": "Sales" }, "CampaignId": "your-campaign-id", "TeamId": "your-team-id", "createdAt": "2025-08-12T15:25:50.939Z", "updatedAt": "2025-08-12T15:25:50.939Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V1 API

bash

curl -X POST 'https://api.supersend.io/v1/contact/create' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Joe", "last_name": "Paul", "email": "joe.paul@example.com", "company_name": "ABC Corp", "TeamId": "your-team-id", "CampaignId": "your-campaign-id" }'

# Response (201 Created) { "message": "Contact created successfully", "contact": { "id": "e8048d7f-3b04-4d6a-b73f-a400b514f626", "email": "joe.paul@example.com", "first_name": "Joe", "last_name": "Paul", "company_name": "ABC Corp", "CampaignId": "your-campaign-id", "OrgId": "org-uuid", "createdAt": "2025-08-12T15:25:50.939Z", "updatedAt": "2025-08-12T15:25:50.939Z" } }

Contact Fields

FieldTypeRequiredDescription

TeamIdstringYesTeam identifier
CampaignIdstringYesCampaign identifier
emailstringOne requiredEmail address
linkedin_urlstringOne requiredLinkedIn profile URL
twitterstringOne requiredTwitter handle
first_namestringNoFirst name
last_namestringNoLast name
company_namestringNoCompany name
titlestringNoJob title
phonestringNoPhone number
citystringNoCity
statestringNoState/Province
countrystringNoCountry
company_urlstringNoCompany website
industrystringNoIndustry
imagestringNoProfile image URL
customobjectNoCustom fields
integration_contact_idstringNoExternal system ID

List Contacts

Get a paginated list of contacts with filtering.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/contacts?TeamId=xxx&CampaignId=yyy&limit=20' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": [ { "id": "contact-uuid", "email": "contact@example.com", "first_name": "John", "last_name": "Doe", "company_name": "Acme Corp", "title": "CEO", "Campaign": { "id": "campaign-uuid", "name": "Q4 Outreach" }, "createdAt": "2025-11-27T10:30:00Z", "updatedAt": "2025-11-27T10:30:00Z" } ], "pagination": { "total": 150, "limit": 20, "offset": 0, "has_more": true }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Query Parameters:

ParameterTypeRequiredDescription

TeamIdstringYesTeam identifier
CampaignIdstringNoFilter by campaign
searchstringNoSearch in email, name, company
deletedbooleanNoInclude deleted contacts
limitnumberNoResults per page (default: 50, max: 100)
offsetnumberNoPagination offset

V1 API

bash

curl -X POST 'https://api.supersend.io/v1/contact/all' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "TeamId": "xxx-xxx-xxx", "CampaignId": "xxx-xxx-xxx", "limit": 50, "offset": 0 }'

# Response { "count": 150, "rows": [...], "verified_count": 120, "valid_count": 100, "paused_count": 5 }

V1 supports additional filters not yet in V2:

verified, validated, finished, bounced, replied, unsubscribed, paused

has_email, has_linkedin, started_sequence

interest, variant, email_provider

Full filter list in V1 documentation below.

Get Contact

Retrieve a single contact by ID.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/contacts/contact-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": { "id": "contact-uuid", "email": "contact@example.com", "first_name": "John", "last_name": "Doe", ... }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V1 API

bash

curl -X GET 'https://api.supersend.io/v1/contact/contact-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "Contact": { "id": "contact-uuid", "email": "contact@example.com", "first_name": "John", "last_name": "Doe", "company_name": "Acme Corp", "CampaignId": "campaign-uuid", "Campaign": { "id": "campaign-uuid", "name": "Q4 Outreach" }, "Sender": { "id": "sender-uuid", "email": "sales@yourcompany.com" } }, "ContactConfig": { "id": "config-uuid", "config": [...] } }

Update Contact

Update an existing contact.

V2 API (Recommended)

bash

curl -X PATCH 'https://api.supersend.io/v2/contacts/contact-uuid' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Jane", "company_name": "New Company" }'

# Response (200 OK) { "success": true, "data": { "id": "contact-uuid", "first_name": "Jane", "company_name": "New Company", ... }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V1 API

bash

curl -X PUT 'https://api.supersend.io/v1/contact/contact-uuid' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Jane", "company_name": "New Company", "TeamId": "xxx", "CampaignId": "xxx" }'

# Response { "success": true, "message": "Contact updated successfully." }

Delete Contact

Delete a contact by ID or by identifier (email/LinkedIn URL).

V2 API (Recommended)

Delete by ID:

bash

curl -X DELETE 'https://api.supersend.io/v2/contacts/contact-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "message": "Contact deleted successfully", "request_id": "req_a1b2c3d4e5f6789012345678" }

Delete by Email:

bash

curl -X DELETE 'https://api.supersend.io/v2/contacts?TeamId=xxx&CampaignId=yyy&email=john@example.com' \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete by LinkedIn URL:

bash

curl -X DELETE 'https://api.supersend.io/v2/contacts?TeamId=xxx&CampaignId=yyy&linkedin_url=https://linkedin.com/in/johndoe' \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk Create Contacts (V1 Only)

Send an array of contacts to bulk create. Duplicates are automatically ignored.

bash

curl -X POST 'https://api.supersend.io/v1/bulk-contacts' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contacts": [ { "email": "contact1@example.com", "first_name": "Alice", "last_name": "Smith" }, { "email": "contact2@example.com", "first_name": "Bob", "last_name": "Jones" } ], "TeamId": "xxx-xxx-xxx", "CampaignId": "xxx-xxx-xxx" }'

# Response { "message": "Upload received. Processing will begin shortly.", "uploadId": "upload-uuid" }

Bulk Actions (V1 Only)

Perform bulk actions on multiple contacts.

Endpoint: POST /v1/contact/bulk-action

Available Actions

ActionDescription

get_contactsGet contacts matching filters
verify_contactsMark contacts as verified
unverify_contactsMark contacts as unverified
verify_passed_email_validationVerify contacts that passed email validation
unverify_failed_email_validationUnverify contacts that failed email validation
restartRestart contacts in sequence
finishMark contacts as finished
unfinishMark contacts as not finished
resumeResume paused contacts
archive_unverifiedArchive unverified contacts
archive_allArchive selected contacts
unarchiveUnarchive contacts
transferTransfer to another campaign (requires to_campaign_id)
reassign_active_senderReassign active sender for contacts
assign_stepAssign to specific sequence step (requires node_id and step_number)

Example: Verify Contacts

bash

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "verify_contacts", "campaign_id": "xxx-xxx-xxx", "contact_ids": ["contact-id-1", "contact-id-2"] }'

# Response { "success": true, "message": "Contact(s) verified status updated successfully" }

Example: Transfer Contacts

bash

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "transfer",
    "campaign_id": "source-campaign-id",
    "to_campaign_id": "target-campaign-id",
    "contact_ids": ["contact-id-1", "contact-id-2"]
  }'

V1 Advanced Filters

The V1 /v1/contact/all endpoint supports these additional filters:

Status Filters:

verified - Filter by verified status

validated - Filter by email validation status

finished - Filter by finished status

appointment - Filter by appointment status

bounced - Filter by bounced status

replied - Filter by replied status

unsubscribed - Filter by unsubscribed status

paused - Filter by paused status

Advanced Filters:

has_email - Filter contacts with/without email

has_linkedin - Filter contacts with/without LinkedIn

has_task - Filter contacts with pending tasks

started_sequence - Filter contacts that started sequence

node_id - Filter by current sequence node

interest - Filter by interest level

variant - Filter by A/B test variant

email_provider - Filter by email provider

senderIds - Filter by assigned sender IDs

reply_labels - Filter by conversation label IDs

customs - Filter by custom field values