Create Contact

Our Contact API allows you to add new contacts into the system. This section guides you through the steps to create a contact. Before you start, make sure you have an API key to authenticate your requests.

📘

Allowed Contact Types

This API permits the creation of two distinct types of contacts:

  1. Personal: A contact associated with an individual user
  2. Company: A contact that belongs to a company

When creating a contact, ensure to specify the contact type as either personal or company. Attempts to create contacts with any other type will result in an error.

1. Authenticate to retrieve access token

OAuth Authentication for 8x8 XCaaS APIs is used to get a temporary access_token for use in with this API

Outputs For Next Step:

  • access_token
  • expires_in

The following steps will use the access_token as a Bearer Token form of authentication. This takes the form of the
Authorization header being set to Bearer access_token (Space between Bearer and the access_token)

2. Create Contact Request

Once authenticated, you can create a new contact by sending a POST request to the Contact API with the necessary information.

HTTP Request

POST https://api.8x8.com/contact/api/v3/contacts

Request Headers

NameRequiredDescriptionExample
AuthorizationPass the access_token returned from the authentication request as a Bearer token Bearer {access_token}Bearer kfjdfi3jfopajdkf93fa9pjfdoiap
Content-TypeThis indicates that the request body is in JSON formatapplication/json

Body for Personal Contact

{
        "customerId": "testCustomerId",
        "siteId": "US1",
        "pbxId": "test-pbx-id",
        "pbxName": "test-pbx-name",
        "contactType": "personal",
        "firstName": "John",
        "lastName": "Doe",
        "nickName": "johnny",
        "jobTitle": "Software Eng.",
        "department": "Research and Development",
        "companyName": "8x8, Inc.",
        "timeZone": "Europe/Athens",
        "locale": "en_US",
        "location": "Romania, Cluj Office",
        "userContact": {
            "userId": "testUserId-synthetic",
            "favorite": true
        },
        "addresses": [
            {
                "country": "Romania",
                "county": "Cluj",
                "city": "Cluj-Napoca",
                "postalCode": "428888",
                "streetName": "Dorobantilor",
                "streetNumber": "24B",
                "notes": "any note",
                "purposeType": "WORK",
                "primary": true
            }
        ],
        "phones": [
            {
                "phone": "0752111111",
                "purposeType": "WORK",
                "primary": true,
                "source": "EXTERNAL"
            }
        ],
        "emails": [
            {
                "email": "[email protected]",
                "purposeType": "work",
                "primary": true
            }
        ],
        "tags": [
            {
                "name": "customField1",
                "value": "value1"
            }
        ]
    }

🚧

Important: Specific Requirements for Personal Contacts

When creating a personal contact, it is essential to set assignedUserId to null and include a userContact object with a valid userId.

The userContact object is crucial as it associates the contact with a particular user. Omitting this information or providing an assignedUserId will result in the rejection of the API request.

Body for Company Contact

{
        "customerId": "testCustomerId",
        "siteId": "US1",
        "pbxId": "test-pbx-id",
        "pbxName": "test-pbx-name",
        "contactType": "compan",
        "firstName": "John",
        "lastName": "Doe",
        "nickName": "johnny",
        "jobTitle": "Software Eng.",
        "department": "Research and Development",
        "companyName": "8x8, Inc.",
        "timeZone": "Europe/Athens",
        "locale": "en_US",
        "location": "Romania, Cluj Office",
        "addresses": [
            {
                "country": "Romania",
                "county": "Cluj",
                "city": "Cluj-Napoca",
                "postalCode": "428888",
                "streetName": "Dorobantilor",
                "streetNumber": "24B",
                "notes": "any note",
                "purposeType": "WORK",
                "primary": true
            }
        ],
        "phones": [
            {
                "phone": "0752111111",
                "purposeType": "WORK",
                "primary": true,
                "source": "EXTERNAL"
            }
        ],
        "emails": [
            {
                "email": "[email protected]",
                "purposeType": "work",
                "primary": true
            }
        ],
        "tags": [
            {
                "name": "customField1",
                "value": "value1"
            }
        ]
    }

⚠️

Important: Specific Requirements for Company Contacts

For company contacts, ensure that both assignedUserId and userContact are excluded from your request. Since a company contact does not belong to an individual user but to a company as a whole, including assignedUserId or userContact will lead to an invalid request.

Detailed Field Descriptions

Basic Information

NameTypeDescriptionExample
idstringUnique identifier for the contactnull (auto-generated)
customerIdstringIdentifier for the customer to whom the contact belongs0016C00000VM1BeQAX
assignedUserIdstringIdentifier for the user to whom the contact is assignedbhjLT03CTJuVwgAy9y3DOQ
siteIdstringIdentifier for the site where the contact is locatedUS1
pbxIdstringIdentifier for the PBX associated with the contacttVKVBdSAyj1syck_-13A
pbxNamestringName of the PBX associated with the contactvoeditionworkflow25
branchIdstringIdentifier for the branch where the contact is locatedbr_301
branchNamestringName of the branch where the contact is locatedDowntownBranch
contactTypestringType of contact, e.g., personal or companypersonal
firstNamestringFirst name of the contactAlicia
lastNamestringLast name of the contactRodriguez
middleNamestringMiddle name of the contact.B.
nickNamestringNickname or informal name used for the contactAli
jobTitlestringProfessional title of the contactAccount Manager
departmentstringDepartment within the company where the contact worksSales and Marketing
companyNamestringName of the company the contact is associated withInnovatech Solutions Inc.
timeZonestringTime zone where the contact is locatedAmerica/New_York
localestringLocale setting representing the contact's language and region formaten_US
locationstringPhysical or office location of the contactNew York Office
displayWhenNoExtensionbooleanFlag to display the contact when there is no extension numberfalse
hideInAAbooleanFlag to hide the contact in the Auto Attendanttrue

User Contact Information

NameTypeDescriptionExample
userIdstringIdentifier for the user profile within the systemnull (auto-generated)
favoritebooleanIndicates if the contact is marked as a favorite by the user0016C00000VM1BeQAX

Addresses

NameTypeDescriptionExample
countrystringIdentifier for the user profile within the systemRomania
countystringIndicates if the contact is marked as a favorite by the userCluj
citystringThe city of the contact’s addressCluj-Napoca
postalCodestringThe postal or ZIP code for the address428888
streetNamestringThe name of the street for the addressDorobantilor
streetNumberstringThe house or building number24B
notesstringAdditional notes about the addressany note
purposeTypestringThe intended use of the address (e.g., WORK, HOME)WORK
primarybooleanIndicates if this is the primary address for the contacttrue

Phones

NameTypeDescriptionExample
phonestringThe phone number associated with the contact0752111111
purposeTypestringThe intended use of the phone number (e.g., WORK, HOME)WORK
primarybooleanIndicates if this is the primary phone number for the contacttrue
sourcestringOrigin of the phone number (e.g., PROVISIONED, EXTERNAL)EXTERNAL

Emails

NameTypeDescriptionExample
emailstringThe email address associated with the contact.0752111111
purposeTypestringThe intended use of the email address (e.g., work, personal)WORK
primarybooleanIndicates if this is the primary email address for the contacttrue

Tags

NameTypeDescriptionExample
namestringThe name or key of the tagcustomField1
valuestringThe value assigned to the tagvalue1

Response

A successful creation will yield a 200 status code and a response body with the details of the new contact, including a contactId. Save the contactId for any future reference.

Example response:


{
  			"id": "c3697cef-5e57-41cc-8720-6db6e8e2a977",
        "customerId": "testCustomerId",
        "siteId": "US1",
        "pbxId": "test-pbx-id",
        "pbxName": "test-pbx-name",
        "contactType": "personal",
        "firstName": "John",
        "lastName": "Doe",
        "nickName": "johnny",
        "jobTitle": "Software Eng.",
        "department": "Research and Development",
        "companyName": "8x8, Inc.",
        "timeZone": "Europe/Athens",
        "locale": "en_US",
        "location": "Romania, Cluj Office",
        "userContact": {
         	  "contactId": "c3697cef-5e57-41cc-8720-6db6e8e2a977",
            "userId": "testUserId-synthetic",
            "favorite": true
        },
        "addresses": [
            {
             	  "id": 4038640,
                "country": "Romania",
                "county": "Cluj",
                "city": "Cluj-Napoca",
                "postalCode": "428888",
                "streetName": "Dorobantilor",
                "streetNumber": "24B",
                "notes": "any note",
                "purposeType": "WORK",
                "primary": true
            }
        ],
        "phones": [
            {
              	"id": 3115834,
                "phone": "0752111111",
                "purposeType": "WORK",
                "primary": true,
                "source": "EXTERNAL"
            }
        ],
        "emails": [
            {
              	"id": 5106367,
                "email": "[email protected]",
                "purposeType": "work",
                "primary": true
            }
        ],
        "tags": [
            {
              	"id": 3228976,
                "name": "customField1",
                "value": "value1"
            }
        ]
}