Create Contact

Create a new contact in your tenant account.

Authentication

Required Scope: contacts:write

Feature Limits

This endpoint respects tenant feature limits for contacts. If the limit is reached, a FEATURE_LIMIT_EXCEEDED error is returned with details about current usage and maximum allowed.

Request Body

Field	Type	Required	Validation	Description
`firstname`	string	Yes	max:255	First name
`lastname`	string	Yes	max:255	Last name
`phone`	string	Yes	max:20, unique per tenant	Phone number with country code
`type`	string	Yes	`lead`, `customer`, `guest`	Contact type
`source_id`	integer	Yes	must exist in tenant sources	Source ID
`status_id`	integer	Yes	must exist in tenant statuses	Status ID
`email`	string	No	email, max:191, unique per tenant	Email address
`company`	string	No	max:255	Company name
`description`	string	No	—	Additional notes
`city`	string	No	max:255	City
`state`	string	No	max:255	State/province
`zip`	string	No	max:20	ZIP/postal code
`address`	string	No	max:500	Street address
`country_id`	integer	No	—	Country ID
`assigned_id`	integer	No	—	User ID to assign contact to
`groups`	array	No	array of integers	Array of group IDs to assign

Response

Success (201 Created): Returns the created contact data wrapped in ContactResource format with groups auto-loaded. Includes message: "Contact created successfully".

Error Responses

Status	Code	Description
422	`VALIDATION_ERROR`	Validation failed (missing required fields, duplicate phone/email, invalid source_id/status_id)
403	`FEATURE_LIMIT_EXCEEDED`	Tenant contact limit reached. Response includes `feature`, `current`, and `maximum` in error details
500	`INTERNAL_ERROR`	Failed to create contact

Validation Error Messages

Field	Message
`firstname`	First name is required
`lastname`	Last name is required
`phone`	Phone number is required / This phone number already exists
`email`	This email address already exists
`type`	Type must be either lead, customer, or guest
`source_id`	The selected source does not exist or does not belong to your account
`status_id`	The selected status does not exist or does not belong to your account

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Authentication#

Feature Limits#

Request Body#

Response#

Error Responses#

Validation Error Messages#