Creating Contacts

Beta

Create new contacts in your workspace with their attributes and subscription preferences. Contacts are identified by either email or phone number, which serve as unique identity fields for your contact database.

Identity Fields

Understanding how contacts are uniquely identified

Contacts in Leadpush are uniquely identified by identity fields. You must provide at least one of the following:

  • Email Address: Primary identifier for email-based contacts
  • Phone Number: Primary identifier for SMS-based contacts
POST

Create Contact

https://api.leadpush.io/v1/workspaces/{workspace_uuid}/contacts

Create a new contact in your workspace

Path parameters

workspace_uuidstring Required

ID of your workspace

Request body

attributesobject Required
Email Identity Request
curl -X POST https://api.leadpush.io/v1/workspaces/{workspace_uuid}/contacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "subscribed": true,
    "attributes": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Corp"
    }
  }'
Example Response
{
  "uuid": "<contact_uuid>",
  "subscribed": true,
  "attributes": {
    "email": "john_doe@leadpush.io",
    "phone": "+1234567890",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Acme Corp"
  },
  "created_at": "2021-01-01T00:00:00.000Z",
  "updated_at": "2021-01-01T00:00:00.000Z"
}

Best Practices

Recommendations for creating contacts effectively

Data Quality

  • Always validate email and phone formats before sending
  • Use consistent phone number formatting (include country codes)
  • Normalize data (trim whitespace, standardize casing)

Handling Duplicates

  • The API will reject duplicate contacts with the same email or phone number
  • Use the uuid field to identify existing contacts
  • Use the updated_at timestamp to detect if a contact was updated vs created
  • Consider implementing idempotency in your application logic

Custom Attributes

  • Use descriptive field names for custom attributes
  • Keep attribute names consistent across your application
  • Consider data types when setting attribute values