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 an array of contacts to bulk create contacts. If you have more than 100 contacts, you can split them into multiple requests.

bash

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
  }
}

bash

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"
}

Create Contacts (Bulk)

Duplicates will automatically be ignored.

Get Contacts

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

Get Contact

Sorting & Pagination:

Update Contact

Get a single contact by ID.

bash

email_security_service

Bulk Contact Actions

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

bash

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
}

bash

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": [...]
  }
}

Examples

bash

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."
}

bash

POST /v1/contact/bulk-action

bash

{
  "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
  }
}