ZooTools is now SMASHSEND Email MarketingRead update

email marketing

Getting Started

API Resources

Support

Get Help

Home

Docs

API Reference

Contact Properties

Contact Properties API

The Contact Properties API allows you to create and manage custom fields for contacts. This is essential for Zapier integrations and other automation platforms that need to sync additional data fields from CRMs, e-commerce platforms, and other business systems.

Overview

Contact properties are custom fields that extend the default contact schema. Common use cases include storing job titles, company information, lead sources, subscription preferences, and any other business-specific data.

Property Types: STRING, TEXT, EMAIL, URL, PHONE, DATE, NUMBER, INTEGER, BOOLEAN

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

Contact Properties Endpoints

GET/v1/contact-properties

Lists all contact properties for the authenticated workspace. Perfect for Zapier integrations to dynamically discover available custom fields.

Query Parameters

type - Filter by property type (optional)

limit - Maximum number of properties to return (default: 100)

Request

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

Response

{
  "properties": {
    "items": [
      {
        "createdAt": "2025-06-04T05:25:48.742Z",
        "description": "The unique identifier of the contact",
        "displayName": "Email",
        "id": "email",
        "isInternal": true,
        "apiSlug": "email",
        "type": "STRING",
        "typeConfig": {},
        "updatedAt": "2025-06-04T05:25:48.742Z",
        "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer",
        "options": []
      },
      {
        "id": "cpd_SXag0kCw5p4yCrEItHQQHoew",
        "apiSlug": "company",
        "createdAt": "2025-06-04T05:26:13.716Z",
        "description": "Company name of the contact",
        "displayName": "Company",
        "isInternal": false,
        "type": "STRING",
        "typeConfig": {},
        "updatedAt": null,
        "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer",
        "options": []
      }
    ],
    "hasMore": false
  }
}

GET/v1/contact-properties/{propertyId}

Retrieves details of a specific contact property.

Path Parameters

propertyId - The unique ID of the contact property (starts with cpd_)

Request

curl "https://api.smashsend.com/v1/contact-properties/cpd_SXag0kCw5p4yCrEItHQQHoew" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "property": {
    "id": "cpd_SXag0kCw5p4yCrEItHQQHoew",
    "apiSlug": "company",
    "displayName": "Company",
    "type": "STRING",
    "description": "Company name of the contact",
    "createdAt": "2025-06-04T05:26:13.716Z",
    "typeConfig": {},
    "updatedAt": null,
    "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer",
    "options": []
  }
}

POST/v1/contact-properties

Creates a new contact property. Essential for setting up custom fields before syncing data from external systems via Zapier.

Request Body Parameters

apiSlug - Unique identifier for API calls (required, lowercase, no spaces)

displayName - Human-readable name shown in UI (required)

type - Data type: STRING, TEXT, EMAIL, URL, PHONE, DATE, NUMBER, INTEGER, BOOLEAN (required)

description - Optional description for the property

Request

curl -X POST "https://api.smashsend.com/v1/contact-properties" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Lead Source",
    "type": "STRING",
    "description": "Where this contact was acquired from",
    "typeConfig": {}
  }'

Response

{
  "property": {
    "id": "cpd_stu901vwx234",
    "apiSlug": "leadSource",
    "displayName": "Lead Source",
    "type": "STRING",
    "description": "Where this contact was acquired from",
    "createdAt": "2024-03-21T14:30:00Z",
    "typeConfig": {},
    "updatedAt": null,
    "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer",
    "options": []
  }
}

PUT/v1/contact-properties/{propertyId}

Updates an existing contact property. Note that the apiSlug and type cannot be changed after creation.

Request

curl -X PUT "https://api.smashsend.com/v1/contact-properties/cpd_SXag0kCw5p4yCrEItHQQHoew" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Company Name",
    "description": "Full legal company name of the contact"
  }'

Response

{
  "property": {
    "id": "cpd_SXag0kCw5p4yCrEItHQQHoew",
    "apiSlug": "company",
    "displayName": "Company Name",
    "type": "STRING",
    "description": "Full legal company name of the contact",
    "createdAt": "2025-06-04T05:26:13.716Z",
    "typeConfig": {},
    "updatedAt": "2024-03-21T16:45:00Z",
    "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer",
    "options": []
  }
}

DELETE/v1/contact-properties/{propertyId}

Permanently deletes a contact property. This will also remove all data stored in this property for all contacts. Use with extreme caution.

Request

curl -X DELETE "https://api.smashsend.com/v1/contact-properties/cpd_SXag0kCw5p4yCrEItHQQHoew" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "deleted": true
}

Property Types Reference

STRING

Short text values, ideal for names, categories, statuses. Maximum 255 characters.

TEXT

Long text values for descriptions, notes, comments. No character limit.

Email addresses with automatic validation.

URL

Website URLs with automatic validation.

PHONE

Phone numbers with flexible formatting.

DATE

Date values in ISO 8601 format (YYYY-MM-DD).

NUMBER

Decimal numbers for prices, ratings, percentages.

INTEGER

Whole numbers for counts, ages, quantities.

BOOLEAN

True/false values for flags, preferences, statuses.

Using Properties with Contacts API

Once you create contact properties, you can use them in the Contacts API by referencing their apiSlug in the customProperties object:

// Create a contact with custom properties
curl -X POST "https://api.smashsend.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "company": "ACME Corp",
      "jobTitle": "Marketing Manager",
      "leadSource": "website",
      "isCustomer": true
    }
  }'

Common Integration Examples

CRM Integration Properties

{
  "company": "STRING",
  "jobTitle": "STRING", 
  "industry": "STRING",
  "annualRevenue": "NUMBER",
  "leadScore": "INTEGER",
  "lastContactDate": "DATE",
  "isQualified": "BOOLEAN"
}

E-commerce Integration Properties

{
  "customerSince": "DATE",
  "totalOrders": "INTEGER",
  "lifetimeValue": "NUMBER",
  "preferredCategory": "STRING",
  "isVip": "BOOLEAN",
  "lastPurchaseDate": "DATE"
}

Form Integration Properties

{
  "formSource": "STRING",
  "referralSource": "STRING",
  "interests": "TEXT",
  "budget": "STRING",
  "timeline": "STRING",
  "hasOptedInMarketing": "BOOLEAN"
}

Error Handling

400 - Validation Error

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "apiSlug must be unique and contain only lowercase letters, numbers, and underscores"
}

409 - Property Already Exists

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "A property with this apiSlug already exists"
}