Skip to main content
Version: v3New

Create Contact

POST 
/contacts/

Create a new contact

Request​

Version stringrequired

API Version

Available optionsv3
application/json

Bodyrequired

    firstNamestringnullable

    First name of the contact

    lastNamestringnullable

    Last name of the contact

    namestringnullable

    Full name of the contact

    emailstringnullable

    Email address of the contact

    locationIdstringrequired

    Location Id the contact should be created under

    genderstring

    Gender of the contact

    phonestringnullable

    Phone number of the contact

    address1stringnullable

    Street address of the contact

    citystringnullable

    City of the contact

    statestringnullable

    State of the contact

    postalCodestring

    Postal code of the contact

    websitestringnullable

    Website URL of the contact

    timezonestringnullable

    Timezone of the contact

    dndboolean

    Whether Do Not Disturb is enabled for the contact

    inboundDndSettingsobject

    Inbound DND settings per channel for the contact

    tagsstring[]

    List of tags to assign to the contact

    customFieldsobject[]

    List of custom field values to assign to the contact

    sourcestring

    Source from which the contact was created

    dateOfBirthobjectnullable

    The birth date of the contact. Supported formats: YYYY/MM/DD, MM/DD/YYYY, YYYY-MM-DD, MM-DD-YYYY, YYYY.MM.DD, MM.DD.YYYY, YYYY_MM_DD, MM_DD_YYYY

    countrystring

    Country code of the contact (ISO 3166-1 alpha-2)

    companyNamestringnullable

    Company name of the contact

    assignedTostring

    User's Id

    additionalEmailsobject[]

    Add additional email addresses to a contact.

    ⚠️ Important: When sending additionalEmails, you must also include the contact’s current primary email in the same request.
    If you send additionalEmails without email, the contact’s existing primary email may be cleared or replaced.

    • email represents the contact’s primary email address.
    • additionalEmails represents secondary email addresses for the same contact.
    • Always send the primary email together with additionalEmails when updating email addresses.
    • A maximum of 10 additional email addresses can be provided.

    Example

    {
      "email": "[email protected]",
      "additionalEmails": [
        {
          "email": "[email protected]"
        }
      ]
    }

    Avoid

    {
      "additionalEmails": [
        {
          "email": "[email protected]"
        }
      ]
    }

    Sending only additionalEmails may cause the existing primary email to be lost.

    If email uniqueness is enabled for the location, every email address in the request—primary and additional—must be unique across contacts. If any email already belongs to another contact, the request fails with 400 Bad Request and no changes are saved.

    Possible values: <= 10

    additionalPhonesobject[]

    Add additional phone numbers to a contact.

    ⚠️ Important: When sending additionalPhones, you must also include the contact’s current primary phone in the same request.
    If you send additionalPhones without phone, the contact’s existing primary phone may be cleared or replaced.

    • phone represents the contact’s primary phone number.
    • additionalPhones represents secondary phone numbers for the same contact.
    • Always send the primary phone together with additionalPhones when updating phone numbers.
    • A maximum of 10 additional phone numbers can be provided.
    • phoneLabel is optional. Allowed values: Home, Work, Mobile, or Landline. A label can belong to only one phone number on the contact, including the primary. If a label is repeated, it is kept on the first phone number and removed from the others.

    Example

    {
      "phone": "+14155550100",
      "additionalPhones": [
        {
          "phone": "+14155550101",
          "phoneLabel": "Work"
        }
      ]
    }

    Avoid

    {
      "additionalPhones": [
        {
          "phone": "+14155550101",
          "phoneLabel": "Work"
        }
      ]
    }

    Sending only additionalPhones may cause the existing primary phone number to be lost.

    If phone uniqueness is enabled for the location, every phone number in the request—primary and additional—must be unique across contacts. If any phone number already belongs to another contact, the request fails with 400 Bad Request and no changes are saved.

    Possible values: <= 10

    dndSettingsobject

    Per-channel DND settings for the contact

application/json

Successful response

Schema
    contactobject

    Contact details