Create new contact

Create a new contact with duplicate checking and comprehensive data validation

POST

https://api.channelautomation.com/api/contacts

Authorization

ApiKeyAuth
API key in header
required

Request body JSON required

workspace_id
string
required
Workspace ID for data isolation
firstname
string
required
Contact's first name

maxLength: 100
lastname
string
required
Contact's last name

maxLength: 100
phone_number
string
required
Contact's phone number in E.164 format

pattern: ^\+[1-9]\d{1,14}$
email
optional
string
Contact's email address

format: email
lead_status
optional
string
Initial lead status
lead_source
optional
string
Source of the lead
product
optional
string
Product of interest
address
optional
string
Street address

maxLength: 255
city
optional
string
City

maxLength: 100
state
optional
string
State or province

maxLength: 50
zip
optional
string
ZIP or postal code

maxLength: 20
notes
optional
string
Additional notes about the contact

maxLength: 1000
tags
optional
array of
string
Array of tags to associate with contact
priority
optional
low
or
medium
or
high
or
urgent
Contact priority level

default: "medium"
opt_in_through
optional
string
How contact opted in for communications

default: "api"
follow_up_date
optional
string
Follow-up date (YYYY-MM-DD)

format: date

Example requests

{
  "workspace_id": "15213",
  "firstname": "John",
  "lastname": "Doe",
  "phone_number": "+1234567890",
  "email": "john.doe@example.com",
  "lead_status": "new",
  "lead_source": "website"
}

{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "firstname": "Jane",
  "lastname": "Smith",
  "phone_number": "+1987654321",
  "email": "jane.smith@example.com",
  "lead_status": "qualified",
  "lead_source": "referral",
  "product": "enterprise_plan",
  "address": "456 Oak Avenue",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94102",
  "notes": "Interested in enterprise features",
  "tags": [
    "enterprise",
    "high-value"
  ],
  "priority": "high",
  "follow_up_date": "2024-02-15"
}

Returns

201

Contact created successfully

JSON

success
optional
boolean
contact
optional
object
- firstName
  string
  required
  The contact's first name
- phone
  string
  required
  The contact's phone number
- workspaceId
  string
  required
  The workspace ID this contact belongs to
- id
  optional
  string
  The auto-generated ID of the contact
- workspace_id
  optional
  string
  Workspace ID
- firstname
  optional
  string
  Contact's first name
- lastname
  optional
  string
  Contact's last name
- name
  optional
  string
  Full name (auto-generated from firstname + lastname)
- phone_number
  optional
  string
  Contact's phone number in E.164 format
- email
  optional
  string
  The contact's email
  
  format: email
- lead_status
  optional
  string
  Current lead status
- lead_source
  optional
  string
  Source of the lead
- product
  optional
  string
  Product of interest
- address
  optional
  string
  Street address
- city
  optional
  string
  City
- state
  optional
  string
  State or province
- zip
  optional
  string
  ZIP or postal code
- notes
  optional
  string
  Additional notes about the contact
- tags
  optional
  array of
  string
  Array of tags associated with contact
- priority
  optional
  low
  or
  medium
  or
  high
  or
  urgent
  Contact priority level
- opt_in_through
  optional
  string
  How contact opted in for communications
- conversation_status
  optional
  string
  Current conversation status
- last_message_at
  optional
  string
  Timestamp of last message
  
  format: date-time
- created_at
  optional
  string
  The date the contact was created
  
  format: date-time
- updated_at
  optional
  string
  The date the contact was last updated
  
  format: date-time
- follow_up_date
  optional
  string
  Follow-up date
  
  format: date
- webhook_name
  optional
  string
  Name of webhook that created this contact
- lastName
  optional
  string
  The contact's last name
- status
  optional
  string
  The contact's status
}
message
optional
string
duplicate_check
optional
object
- checked
  optional
  boolean
  Whether duplicate checking was performed
- found_duplicates
  optional
  boolean
  Whether duplicates were found
- duplicate_contacts
  optional
  array of
  object
  Array of potential duplicate contacts
  
  firstName
  string
  required
  The contact's first name
  
  phone
  string
  required
  The contact's phone number
  
  workspaceId
  string
  required
  The workspace ID this contact belongs to
  
  id
  optional
  string
  The auto-generated ID of the contact
  
  workspace_id
  optional
  string
  Workspace ID
  
  firstname
  optional
  string
  Contact's first name
  
  lastname
  optional
  string
  Contact's last name
  
  name
  optional
  string
  Full name (auto-generated from firstname + lastname)
  
  phone_number
  optional
  string
  Contact's phone number in E.164 format
  
  email
  optional
  string
  The contact's email
  
  format: email
  lead_status
  optional
  string
  Current lead status
  
  lead_source
  optional
  string
  Source of the lead
  
  product
  optional
  string
  Product of interest
  
  address
  optional
  string
  Street address
  
  city
  optional
  string
  City
  
  state
  optional
  string
  State or province
  
  zip
  optional
  string
  ZIP or postal code
  
  notes
  optional
  string
  Additional notes about the contact
  
  tags
  optional
  array of
  string
  Array of tags associated with contact
  
  priority
  optional
  low
  or
  medium
  or
  high
  or
  urgent
  Contact priority level
  
  opt_in_through
  optional
  string
  How contact opted in for communications
  
  conversation_status
  optional
  string
  Current conversation status
  
  last_message_at
  optional
  string
  Timestamp of last message
  
  format: date-time
  created_at
  optional
  string
  The date the contact was created
  
  format: date-time
  updated_at
  optional
  string
  The date the contact was last updated
  
  format: date-time
  follow_up_date
  optional
  string
  Follow-up date
  
  format: date
  webhook_name
  optional
  string
  Name of webhook that created this contact
  
  lastName
  optional
  string
  The contact's last name
  
  status
  optional
  string
  The contact's status
}

400

Validation error or duplicate contact

JSON

success
optional
boolean
error
optional
string
existing_contact
optional
object
- firstName
  string
  required
  The contact's first name
- phone
  string
  required
  The contact's phone number
- workspaceId
  string
  required
  The workspace ID this contact belongs to
- id
  optional
  string
  The auto-generated ID of the contact
- workspace_id
  optional
  string
  Workspace ID
- firstname
  optional
  string
  Contact's first name
- lastname
  optional
  string
  Contact's last name
- name
  optional
  string
  Full name (auto-generated from firstname + lastname)
- phone_number
  optional
  string
  Contact's phone number in E.164 format
- email
  optional
  string
  The contact's email
  
  format: email
- lead_status
  optional
  string
  Current lead status
- lead_source
  optional
  string
  Source of the lead
- product
  optional
  string
  Product of interest
- address
  optional
  string
  Street address
- city
  optional
  string
  City
- state
  optional
  string
  State or province
- zip
  optional
  string
  ZIP or postal code
- notes
  optional
  string
  Additional notes about the contact
- tags
  optional
  array of
  string
  Array of tags associated with contact
- priority
  optional
  low
  or
  medium
  or
  high
  or
  urgent
  Contact priority level
- opt_in_through
  optional
  string
  How contact opted in for communications
- conversation_status
  optional
  string
  Current conversation status
- last_message_at
  optional
  string
  Timestamp of last message
  
  format: date-time
- created_at
  optional
  string
  The date the contact was created
  
  format: date-time
- updated_at
  optional
  string
  The date the contact was last updated
  
  format: date-time
- follow_up_date
  optional
  string
  Follow-up date
  
  format: date
- webhook_name
  optional
  string
  Name of webhook that created this contact
- lastName
  optional
  string
  The contact's last name
- status
  optional
  string
  The contact's status
}
validation_errors
optional
array of
string

401

Authentication required

JSON

error
optional
string
success
optional
boolean

500

Internal server error

JSON

error
optional
string
details
optional
string
success
optional
boolean

curl --request POST \ --url https://api.channelautomation.com/api/contacts \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <X-API-Key>' \ --data ' { "workspace_id": "15213", "firstname": "John", "lastname": "Doe", "phone_number": "+1234567890", "email": "john.doe@example.com", "lead_status": "new", "lead_source": "website" } '

{ "success": true, "contact": { "id": "string", "workspace_id": "string", "firstname": "John", "lastname": "Doe", "name": "John Doe", "phone_number": "+1234567890", "email": "john.doe@example.com", "lead_status": "qualified", "lead_source": "website", "product": "premium_plan", "address": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "notes": "string", "tags": [ "vip", "enterprise" ], "priority": "high", "opt_in_through": "api", "conversation_status": "active", "last_message_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "follow_up_date": "2019-08-24", "webhook_name": "string", "firstName": "string", "lastName": "string", "phone": "string", "workspaceId": "string", "status": "string" }, "message": "Contact created successfully", "duplicate_check": { "checked": true, "found_duplicates": true, "duplicate_contacts": [ { "id": "string", "workspace_id": "string", "firstname": "John", "lastname": "Doe", "name": "John Doe", "phone_number": "+1234567890", "email": "john.doe@example.com", "lead_status": "qualified", "lead_source": "website", "product": "premium_plan", "address": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "notes": "string", "tags": [ "vip", "enterprise" ], "priority": "high", "opt_in_through": "api", "conversation_status": "active", "last_message_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "follow_up_date": "2019-08-24", "webhook_name": "string", "firstName": "string", "lastName": "string", "phone": "string", "workspaceId": "string", "status": "string" } ] } }

{ "success": false, "error": "Contact with this phone number already exists", "existing_contact": { "id": "string", "workspace_id": "string", "firstname": "John", "lastname": "Doe", "name": "John Doe", "phone_number": "+1234567890", "email": "john.doe@example.com", "lead_status": "qualified", "lead_source": "website", "product": "premium_plan", "address": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "notes": "string", "tags": [ "vip", "enterprise" ], "priority": "high", "opt_in_through": "api", "conversation_status": "active", "last_message_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "follow_up_date": "2019-08-24", "webhook_name": "string", "firstName": "string", "lastName": "string", "phone": "string", "workspaceId": "string", "status": "string" }, "validation_errors": [ "string" ] }