ZooTools is now SMASHSEND Email MarketingRead update

email marketing

Getting Started

API Resources

Support

Get Help

Home

Docs

API Reference

Contacts

Contacts API

The Contacts API allows you to manage contacts in your SMASHSEND account. This API is commonly used by Zapier developers and other integration platforms to sync contact data, create automated workflows, and manage customer information across different systems.

Authentication & Base URL

Base URL: https://api.smashsend.com

All API requests must include your API key in the Authorization header. You can manage your API keys in your SMASHSEND dashboard under Settings → API.

Authorization: Bearer sk_live_abc123...

Rate Limits: API requests are limited to ensure service reliability. For Zapier integrations, we recommend using webhook triggers instead of polling for real-time updates.

Contacts Endpoints

GET/v1/contacts

Lists contacts for the authenticated workspace with cursor-based pagination. Perfect for Zapier “New Contact” triggers and bulk contact synchronization.

Query Parameters

limit - Number of contacts to return (default: 15, max: 100)

cursor - Pagination cursor for getting next page

sort - Sort order: “createdAt.desc” or “createdAt.asc” (default: “createdAt.desc”)

search - Search contacts by email, name, or phone

status - Filter by status: “SUBSCRIBED”, “UNSUBSCRIBED”, or “BANNED”

includeCount - Include total count in response (boolean)

Request

curl "https://api.smashsend.com/v1/contacts?limit=15&sort=createdAt.desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "contacts": {
    "cursor": "MjAyNS0wNi0wMlQwMDoyMDoxNS42OTVa",
    "hasMore": true,
    "items": [
      {
        "id": "ctc_L10vZx0SFrmzKkHwWjoLYSIf",
        "createdAt": "2025-06-02T00:35:15.593Z",
        "updatedAt": "2025-06-04T04:13:20.114Z",
        "properties": {
          "avatarUrl": null,
          "birthday": null,
          "city": null,
          "countryCode": "DZ",
          "email": "contact@example.com",
          "firstName": "John",
          "language": null,
          "lastName": "Doe",
          "phone": "",
          "status": "SUBSCRIBED",
          "company": "ACME Corp"
        },
        "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer"
      }
    ],
    "totalCount": 11
  }
}

GET/v1/contacts/{contactId}

Retrieves a specific contact by ID. Useful for Zapier “Find Contact” actions and getting detailed contact information.

Path Parameters

contactId - The unique ID of the contact (starts with “ctc_”)

Request

curl "https://api.smashsend.com/v1/contacts/ctc_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "contact": {
    "id": "ctc_E7g1zoXJEAkWvgN0yMEIuPOM",
    "createdAt": "2025-06-04T05:26:19.247Z",
    "updatedAt": "2025-06-04T05:26:20.454Z",
    "properties": {
      "avatarUrl": "https://storage.googleapis.com/zootools-beta/workspaces/wrk_ENGTK86JEXXckyDVJthKkPer/contacts/ctc_E7g1zoXJEAkWvgN0yMEIuPOM/avatar",
      "birthday": null,
      "city": null,
      "countryCode": null,
      "email": "test2@example.com",
      "firstName": "Test2",
      "language": null,
      "lastName": "User2",
      "phone": null,
      "status": "SUBSCRIBED",
      "company": "ACME Corp"
    },
    "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer"
  }
}

POST/v1/contacts

Creates a new contact. This is the most common endpoint used by Zapier integrations to add contacts from other platforms like forms, CRMs, and e-commerce systems.

Request Body Parameters

Important: All contact data must be wrapped in a properties object.

properties.email - Contact’s email address (required, must be unique)

properties.firstName - Contact’s first name (optional)

properties.lastName - Contact’s last name (optional)

properties.phone - Contact’s phone number with country code (optional)

properties.avatarUrl - URL to contact’s profile photo (optional)

properties.countryCode - Two-letter ISO country code like “US” (optional)

properties.* - Any custom properties as key-value pairs within the properties object

Request

curl -X POST "https://api.smashsend.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "email": "jane.smith@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "phone": "+1987654321",
      "countryCode": "US",
      "company": "Zapier Inc",
      "jobTitle": "Developer",
      "leadSource": "zapier_integration"
    }
  }'

Response

{
  "contact": {
    "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
    "createdAt": "2025-06-04T05:25:54.134Z",
    "updatedAt": null,
    "properties": {
      "avatarUrl": null,
      "birthday": null,
      "city": null,
      "countryCode": null,
      "email": "test@example.com",
      "firstName": "Test",
      "language": null,
      "lastName": "User",
      "phone": null,
      "status": "SUBSCRIBED"
    },
    "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer"
  }
}

PUT/v1/contacts/{contactId}

Updates an existing contact. Commonly used in Zapier workflows to sync updated information from other systems.

Request

curl -X PUT "https://api.smashsend.com/v1/contacts/ctc_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "firstName": "John",
      "lastName": "Doe Jr.",
      "company": "New Company Inc",
      "jobTitle": "Senior Manager"
    }
  }'

Response

{
  "contact": {
    "id": "ctc_abc123def456",
    "createdAt": "2024-03-20T12:00:00Z",
    "updatedAt": "2024-03-21T14:45:00Z",
    "properties": {
      "avatarUrl": "https://example.com/avatar.jpg",
      "birthday": null,
      "city": null,
      "countryCode": "US",
      "email": "john.doe@example.com",
      "firstName": "John",
      "language": null,
      "lastName": "Doe Jr.",
      "phone": "+1234567890",
      "status": "SUBSCRIBED",
      "company": "New Company Inc",
      "jobTitle": "Senior Manager",
      "leadSource": "website"
    },
    "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer"
  }
}

DELETE/v1/contacts/{contactId}

Permanently deletes a contact. Use with caution as this action cannot be undone.

Request

curl -X DELETE "https://api.smashsend.com/v1/contacts/ctc_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "deleted": true
}

GET/v1/contacts/search

Search for contacts by email address. Perfect for Zapier “Find Contact” actions before creating or updating.

Query Parameters

email - Email address to search for (required)

Request

curl "https://api.smashsend.com/v1/contacts/search?email=john.doe@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "contact": {
    "id": "ctc_abc123def456",
    "createdAt": "2024-03-20T12:00:00Z",
    "updatedAt": "2024-03-20T12:00:00Z",
    "properties": {
      "avatarUrl": null,
      "birthday": null,
      "city": null,
      "countryCode": null,
      "email": "john.doe@example.com",
      "firstName": "John",
      "language": null,
      "lastName": "Doe",
      "phone": null,
      "status": "SUBSCRIBED",
      "company": "ACME Corp"
    },
    "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer"
  }
}

Error Handling

The API uses standard HTTP status codes. Common error responses:

400 - Bad Request

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid email format"
}

404 - Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Contact not found"
}

409 - Conflict

{
  "statusCode": 409,
  "error": "Conflict", 
  "message": "Contact with this email already exists"
}

Custom Properties

Custom properties allow you to store additional data with contacts. They're commonly used to sync data from CRMs, e-commerce platforms, and other business tools via Zapier.

Before using custom properties in API calls, you need to create them in your SMASHSEND dashboard or via the Contact Properties API. See the Contact Properties API documentation for more details.

Common Custom Property Examples

{
  "properties": {
    "email": "contact@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "company": "ACME Corp",
    "jobTitle": "Marketing Manager",
    "leadSource": "website",
    "industry": "Technology",
    "annualRevenue": "100000",
    "isCustomer": true,
    "lastPurchaseDate": "2024-03-15"
  }
}

CRM Integration Properties

{
  "properties": {
    "email": "contact@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "company": "ACME Corp",
    "jobTitle": "Marketing Manager", 
    "industry": "Technology",
    "annualRevenue": 250000,
    "leadScore": 85,
    "lastContactDate": "2024-03-15",
    "isQualified": true,
    "salesRep": "John Smith",
    "dealStage": "Proposal"
  }
}

E-commerce Integration Properties

{
  "properties": {
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "customerSince": "2023-06-15",
    "totalOrders": 12,
    "lifetimeValue": 1850.00,
    "preferredCategory": "Electronics",
    "isVip": true,
    "lastPurchaseDate": "2024-03-10",
    "loyaltyTier": "Gold",
    "averageOrderValue": 154.17
  }
}

Form Integration Properties

{
  "properties": {
    "email": "lead@example.com",
    "firstName": "Mike",
    "lastName": "Johnson",
    "formSource": "Contact Us Page",
    "referralSource": "Google Ads",
    "interests": "Email marketing, automation, analytics",
    "budget": "$1000-5000",
    "timeline": "Next 3 months",
    "hasOptedInMarketing": true,
    "companySize": "50-200 employees",
    "currentTool": "Mailchimp"
  }
}

Zapier Integration Tips

1. Use “Search then Create” Pattern

Always search for existing contacts by email before creating new ones to avoid duplicates.

2. Leverage Custom Properties

Use custom properties to sync additional data from your source systems like CRM fields, e-commerce data, or form responses.

3. Handle Rate Limits

For bulk operations, consider using batch endpoints or implementing delays between requests.

4. Use Webhooks for Real-time Updates

Instead of polling for changes, set up webhooks to get notified when contacts are created, updated, or deleted.