Log InHome Page

APIs

Contact API

A contact is a lead or prospect that you are trying to reach out to. You can add contacts to a campaign and then send them emails, LinkedIn messages, or some Twitter actions like follow.

Create Single Contact

Send a json object to create single contact.

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

curl -X POST 'https://api.supersend.io/v1/contact/create' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "first_name": "Joe",
    "last_name": "Paul",
    "email": "joe.paul@example.com",
    "linkedin_url": null,
    "image": null,
    "title": "manager",
    "phone": "+1-534-634-5346",
    "company_name": "ABC",
    "industry": null,
    "notes": null,
    "company_url": null,
    "one_liner": null,
    "one_liner_2": null,
    "one_liner_3": null,
    "selected_one_liner": "1",
    "twitter": null,
    "city": "Raleigh",
    "state": "NC",
    "country": "United States",
    "integration_contact_id": null,
    "next_node": null,
    "next_step": null,
    "custom": {
        "gender": "M",
        "fax": "+1-344-334-5432"
    },
    "TeamId": "xxxx-xxxx-xxxx-xxxx-xxxxxxx",
    "CampaignId": "xxxxxx-xxxx-xxxxx-xxxxx-xxxxxxx"
}'
# Response
Status Code 201
{
  "message": "Contact created successfully",
  "contact": {
    "id": "e8048d7f-3b04-4d6a-b73f-a400b514f626",
    "validated": false,
    "valid": false,
    "valid2": 0,
    "verified": true,
    "b_test": false,
    "first_name": "Bob",
    "last_name": "Paul",
    "email": "bob.paul@example.com",
    "linkedin_url": null,
    "image": null,
    "title": "manager",
    "phone": "+1-534-634-5347",
    "company_name": "ABC",
    "industry": null,
    "company_url": null,
    "one_liner": null,
    "one_liner_2": null,
    "one_liner_3": null,
    "selected_one_liner": "1",
    "twitter": null,
    "city": "Raleigh",
    "state": "NC",
    "country": "United States",
    "integration_contact_id": null,
    "custom": {
        "fax": "+1-344-334-5432",
        "gender": "M"
    },
    "CampaignId": "144bdb5d-1be1-4a82-bfe1-f691c58ff41f",
    "OrgId": "0d3f8859-531b-4f95-ad93-e6311698e7e6",
    "test_letter": "a",
    "updatedAt": "2025-08-12T15:25:50.939Z",
    "createdAt": "2025-08-12T15:25:50.939Z",
    "timezone_offset": null,
    "note": null,
    "twitter_id": null,
    "interest": null
  }
}

Create Contacts (Bulk)

Send an array of contacts to bulk create contacts. If you have more than 100 contacts, you can split them into multiple requests.

Duplicates will automatically be ignored.

JSON Upload

curl 'https://api.supersend.io/v1/bulk-contacts' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
 "contacts": [
    {
        "email": "test@example.com",
        "first_name": "Bob",
        "last_name": "Builder",
        "phone": "111-222-3333",
        "city": "Las Vegas",
        "state": "NV",
        "country": "USA",
        "title": "co-founder",
        "tags": [],
        "linkedin_url": "linkedin URL",
        "twitter": "twitter name",
        "integration_contact_id": "your system'\''s contact id",
        "company_name": "anything",
        "company_url": "company url",
        "custom": {
          "other1": "qwd"
        }
    }
  ],
  "TeamId": "xxx-xxx-xxx",
  "CampaignId": "xxx-xxx-xxx"
}'

# Response
{
  "message": "Upload received. Processing will begin shortly. If any errors occur, please check your email for a notification.",
  "uploadId": "upload-uuid"
}

Get Contacts

Get a list of contacts with optional filters. All filter fields are optional except TeamId.

Query Parameters

Required:

  • TeamId - string - Team identifier (required)

Optional Filters:

  • CampaignId - string - Filter by campaign ID
  • campaignIds - array - Filter by multiple campaign IDs
  • search - string - Search in email, first_name, last_name, title, company_name, integration_contact_id
  • company_name - string - Filter by company name
  • company_url - string - Filter by company URL
  • linkedin_url - string - Filter by LinkedIn URL
  • phone - string - Filter by phone number
  • twitter - string - Filter by Twitter handle
  • city - string - Filter by city
  • state - string - Filter by state
  • country - string - Filter by country

Status Filters:

  • verified - boolean - Filter by verified status
  • validated - boolean - Filter by email validation status
  • finished - boolean - Filter by finished status
  • appointment - boolean - Filter by appointment status
  • bounced - boolean - Filter by bounced status
  • replied - boolean - Filter by replied status
  • unsubscribed - boolean - Filter by unsubscribed status
  • deleted - boolean - Include/exclude deleted contacts
  • paused - boolean - Filter by paused status

Advanced Filters:

  • has_email - boolean - Filter contacts with/without email
  • has_linkedin - boolean - Filter contacts with/without LinkedIn
  • has_task - boolean - Filter contacts with pending tasks
  • started_sequence - boolean - Filter contacts that started sequence
  • node_id - string - Filter by current sequence node (use "not_started" for contacts not in sequence)
  • reason - string - Filter by pause/error reason
  • interest - string or array - Filter by interest level
  • variant - string - Filter by A/B test variant (a, b, c, d)
  • email_provider - string or array - Filter by email provider (Google, Microsoft, Other)
  • email_security_service - string - Filter by email security service
  • senderIds - array - Filter by assigned sender IDs
  • senderProfileIds - array - Filter by sender profile IDs
  • reply_labels - array - Filter by conversation label IDs
  • customs - object - Filter by custom field values

Sorting & Pagination:

  • sortBy - string - Sort order: oldest, newest, first_name, first_name_desc, last_name, last_name_desc, company_name, company_name_desc, active_campaigns
  • limit - number - Number of records to return (default: 10)
  • offset - number - Number of records to skip (default: 0)
curl -X POST 'https://api.supersend.io/v1/contact/all' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
--data '{
  "TeamId": "xxx-xxx-xxx",
  "CampaignId": "xxx-xxx-xxx",
  "search": "any text",
  "company_name": "Acme Corp",
  "linkedin_url": "http://",
  "phone": "3234",
  "twitter": "",
  "city": "",
  "state": "",
  "country": "",
  "verified": false,
  "validated": true,
  "finished": false,
  "appointment": false,
  "bounced": false,
  "replied": false,
  "unsubscribed": false,
  "paused": false,
  "has_email": true,
  "email_provider": ["Google", "Microsoft"],
  "interest": "high",
  "variant": "a",
  "sortBy": "newest",
  "limit": 50,
  "offset": 0
}'

# Response
{
  "count": 150,
  "rows": [
    {
      "id": "contact-uuid",
      "email": "contact@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Corp",
      "title": "CEO",
      "verified": true,
      "replied": false,
      "conversation_title": "Re: Partnership Opportunity",
      "last_message_text": "Thanks for reaching out...",
      "last_message_date": "2025-11-27T10:30:00Z",
      "labels": [
        {
          "id": "label-uuid",
          "name": "Interested",
          "color": "#4CAF50"
        }
      ],
      "ContactConfig": {
        "config": [...]
      },
      "Campaign": {
        "name": "Q4 Outreach"
      }
    }
  ],
  "contactConfig": {...},
  "verified_count": 120,
  "valid_count": 100,
  "paused_count": 5
}

Get Contact

Get a single contact by ID.

Query Parameters:

  • includeDeleted - boolean (optional) - Include deleted contacts in search
  • project - string (optional) - Project ID to get specific contact config
curl -X GET 'https://api.supersend.io/v1/contact/<ContactId>' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "Contact": {
    "id": "contact-uuid",
    "email": "contact@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "Acme Corp",
    "verified": true,
    "CampaignId": "campaign-uuid",
    ...
  },
  "ContactConfig": {
    "config": [...]
  }
}

Update Contact

Update a single contact by ID. All fields are optional except TeamId and CampaignId.

curl -X PUT https://api.supersend.io/v1/contact/<ContactId> \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "email": "updated@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1-555-1234",
  "image": "https://example.com/photo.jpg",
  "title": "CEO",
  "replied": true,
  "bounced": false,
  "appointment": true,
  "finished": false,
  "verified": true,
  "unsubscribed": false,
  "deleted": false,
  "company_name": "Acme Corp",
  "company_url": "https://acme.com",
  "industry": "Technology",
  "one_liner": "Custom message 1",
  "one_liner_2": "Custom message 2",
  "one_liner_3": "Custom message 3",
  "selected_one_liner": "1",
  "generateOneLiners": false,
  "linkedin_url": "https://linkedin.com/in/johndoe",
  "twitter": "johndoe",
  "next_node": "node-uuid",
  "next_step": 2,
  "interest": "high",
  "city": "San Francisco",
  "state": "CA",
  "country": "United States",
  "notes": "Important client",
  "taskNote": "Follow up next week",
  "custom": {
    "department": "Sales",
    "employee_count": "50-100"
  },
  "integration_contact_id": "ext-12345",
  "TeamId": "xxx-xxx-xxx",
  "CampaignId": "xxx-xxx-xxx"
}'

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

Bulk Contact Actions

Perform bulk actions on multiple contacts. You can either specify exact contact IDs or use filters with an exclusion list (for "select all except" functionality).

Endpoint: POST /v1/contact/bulk-action

Available Actions

  1. get_contacts - Retrieve contacts matching criteria
  2. verify_contacts - Mark contacts as verified
  3. unverify_contacts - Mark contacts as unverified
  4. verify_passed_email_validation - Verify contacts that passed email validation
  5. unverify_failed_email_validation - Unverify contacts that failed validation
  6. restart - Restart contacts in sequence (clears progress and resets to step 0)
  7. finish - Mark contacts as finished
  8. unfinish - Mark contacts as not finished
  9. resume - Resume paused contacts
  10. archive_unverified - Archive unverified contacts
  11. archive_all - Archive all selected contacts
  12. unarchive - Unarchive contacts
  13. transfer - Transfer contacts to another campaign
  14. reassign_active_sender - Reassign active sender to contacts
  15. assign_step - Assign contacts to specific sequence step

Request Body

{
  "action": "string (required)",
  "campaign_id": "uuid (optional)",
  "to_campaign_id": "uuid (required for 'transfer' action)",
  "node_id": "string (required for 'assign_step' action)",
  "step_number": "number (required for 'assign_step' action)",
  "contact_ids": ["uuid"],
  "exclude_ids": ["uuid"],
  "filters": {
    // Same filters as Get Contacts endpoint
  }
}

Note: Provide either contact_ids (specific contacts) OR exclude_ids (all except these), but not both.

Examples

Verify Specific Contacts

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \
-H "Authorization: Bearer <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"
}

Restart All Unverified Contacts

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "action": "restart",
  "campaign_id": "xxx-xxx-xxx",
  "filters": {
    "verified": false
  }
}'

# Response
{
  "success": true,
  "message": "Selected contact restarted successfully"
}

Transfer Contacts to Another Campaign

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \
-H "Authorization: Bearer <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"]
}'

# Response
{
  "success": true,
  "message": "successfully"
}

Assign Contacts to Specific Step

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "action": "assign_step",
  "campaign_id": "xxx-xxx-xxx",
  "node_id": "message-node-uuid",
  "step_number": 3,
  "contact_ids": ["contact-id-1", "contact-id-2"]
}'

# Response
{
  "success": true,
  "message": "Contact(s) successfully assigned to step"
}

Resume Paused Contacts (Select All Except)

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "action": "resume",
  "campaign_id": "xxx-xxx-xxx",
  "exclude_ids": ["contact-to-exclude-1", "contact-to-exclude-2"],
  "filters": {
    "paused": true
  }
}'

# Response
{
  "success": true,
  "message": "Contact(s) resumed successfully",
  "count": 45
}

Archive All Bounced Contacts

curl -X POST 'https://api.supersend.io/v1/contact/bulk-action' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "action": "archive_all",
  "campaign_id": "xxx-xxx-xxx",
  "filters": {
    "bounced": true
  }
}'

# Response
{
  "success": true,
  "message": "Contacts archived successfully"
}
Previous
Authentication
Next
Campaigns