Creating Contacts

Beta

Create new contacts in your workspace with their attributes. Contacts are identified by your workspace identity field (email by default), which must be included in the request. New contacts are subscribed by default.

Identity Fields

Understanding how contacts are uniquely identified

Contacts in Leadpush are uniquely identified by your workspace identity field. You must provide the required identity attribute in attributes based on your workspace configuration.

  • Email Address: Default identifier for email-based contacts
  • Phone Number: Identifier for SMS-based contacts when your workspace identity is set to phone
  • Custom Identity Field: If configured, this field is required in place of email or phone
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 '{
    "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 identity field value
  • Use the upsert endpoint to create-or-update contacts without duplication errors
  • 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