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

Field	Type	Required	Description
`TeamId`	string	Yes	Team identifier
`CampaignId`	string	Yes	Campaign identifier
`email`	string	One required	Email address
`linkedin_url`	string	One required	LinkedIn profile URL
`twitter`	string	One required	Twitter handle
`first_name`	string	No	First name
`last_name`	string	No	Last name
`company_name`	string	No	Company name
`title`	string	No	Job title
`phone`	string	No	Phone number
`city`	string	No	City
`state`	string	No	State/Province
`country`	string	No	Country
`company_url`	string	No	Company website
`industry`	string	No	Industry
`image`	string	No	Profile image URL
`custom`	object	No	Custom fields
`integration_contact_id`	string	No	External 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:

Parameter	Type	Required	Description
`TeamId`	string	Yes	Team identifier
`CampaignId`	string	No	Filter by campaign
`search`	string	No	Search in email, name, company
`deleted`	boolean	No	Include deleted contacts
`limit`	number	No	Results per page (default: 50, max: 100)
`offset`	number	No	Pagination 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

Import contacts in bulk via JSON array or CSV file upload. Processing happens asynchronously.

V2 API (Recommended)

bash

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

# Response (202 Accepted) { "success": true, "data": { "upload_id": "upload-uuid", "status": "pending", "contact_count": 2, "message": "Upload received. Processing will begin shortly." }, "request_id": "req_a1b2c3d4e5f6789012345678" }

CSV Upload (multipart/form-data):

bash

curl -X POST 'https://api.supersend.io/v2/contacts/bulk' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "contacts=@contacts.csv" \
  -F "TeamId=xxx-xxx-xxx" \
  -F "CampaignId=xxx-xxx-xxx" \
  -F 700 dark:text-green-400">'mapping_fields={"Email": "email", "First Name": "first_name", "Last Name": "last_name"}'

Limits:

Maximum 50,000 contacts per request

Subject to your organization's contact limit

V1 API

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

Action	Description
`get_contacts`	Get contacts matching filters
`verify_contacts`	Mark contacts as verified
`unverify_contacts`	Mark contacts as unverified
`verify_passed_email_validation`	Verify contacts that passed email validation
`unverify_failed_email_validation`	Unverify contacts that failed email validation
`restart`	Restart contacts in sequence
`finish`	Mark contacts as finished
`unfinish`	Mark contacts as not finished
`resume`	Resume paused contacts
`archive_unverified`	Archive unverified contacts
`archive_all`	Archive selected contacts
`unarchive`	Unarchive contacts
`transfer`	Transfer to another campaign (requires `to_campaign_id`)
`reassign_active_sender`	Reassign active sender for contacts
`assign_step`	Assign 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