Contact Object Structure

This section is dedicated to the Contact object structure, which is a central element in contact management. This guide will help you understand the detailed structure of the Contact object used across various endpoints, such as contact details retrieval, updates, and listings.

📘
Contact Types
In our system, contacts are categorized as follows:

Corporate or Service

These are pre-configured or system-generated contacts that are essential for the functioning of various services or corporate operations.

Company

These are user-defined or manually added contacts that represent individuals or company entities outside of the core system functionalities.

This API allows modifications to company contacts only. You can create, update or delete company contacts as needed. Please note that modifications to other types of contacts are not supported

Contact JSON Object Structure

Below is the detailed JSON structure of the Contact object. This structure is utilized in several API endpoints related to contact operations.

{
    "id": "2h_JNsaISleZWA36GRh3YQ",
    "assignedUserId": "2h_JNsaISleZWA36GRh3YQ",
    "branchId": "ovYzzgfDSDqolA3RbhWjbw",
    "branchName": "Tech Support Division",
    "companyName": "8x8 Inc.",
    "contactType": "corporate",
    "createdTimestamp": 1621341000000,
    "customerId": "0016C00000VM1BeQAL",
    "department": "Support",
    "displayWhenNoExtension": true,
    "firstName": "James",
    "hideInAA": false,
    "jobTitle": "Agent",
    "lastName": "Miller",
    "locale": "en_US",
    "middleName": "Edward",
    "name": "James Edward Miller",
    "nickName": "Jim",
    "pbxId": "bhjLT03CTJuVwgAy9y3DOQ",
    "pbxName": "qmsarealenv1",
    "pictureHash": "a046a853f0e131f18001d1174d8588ff76172a1350ba5ff1ba081caa470f6e1e",
    "timeZone": "America/Los_Angeles",
    "updatedTimestamp": 1678182231575,
    "addresses": [
        {
            "id": 23071,
            "apartmentNumber": null,
            "city": "San Jose",
            "country": "United States",
            "county": "Santa Clara",
            "notes": "8x8 Headquarters",
            "postalCode": "95131",
            "primary": true,
            "purposeType": "WORK",
            "state": "California",
            "streetName": "1st St",
            "streetNumber": "675"
        }
    ],
    "emails": [
        {
            "id": 86533,
            "email": "[email protected]",
            "primary": true,
            "purposeType": "WORK"
        }
    ],
    "extensions": [
        {
            "id": 52400,
            "branchId": "ovYzzgfDSDqolA3RbhWjbw",
            "branchName": "ContactSite",
            "contactId": "2h_JNsaISleZWA36GRh3YQ",
            "displayInDirectory": true,
            "extension": "60000001",
            "extensionType": "CC",
            "fqExtension": "1460000001",
            "pbxId": "bhjLT03CTJuVwgAy9y3DOQ",
            "pbxName": "qmsarealenv1",
            "subscriptionId": "aK60JcBERnKIya9Rt7BCxA",
            "subscriptionType": "UE"
        }
    ],
    "phones": [
        {
            "id": 48073,
            "phone": "04029511367",
            "primary": true,
            "purposeType": "WORK",
            "source": "EXTERNAL"
        },
        {
            "id": 48074,
            "phone": "0756124412",
            "primary": false,
            "purposeType": "HOME",
            "source": "EXTERNAL"
        }
    ],
    "tags": [
        {
            "id": 25672,
            "name": "customField2",
            "value": "value2"
        },
        {
            "id": 25673,
            "name": "customField1",
            "value": "value_updated"
        },
        {
            "id": 25674,
            "name": "customField3",
            "value": "value3"
        }
    ]
}

🚧
Legacy Field Usage
In the latest version of our application, we have retained certain fields from the previous system iteration, such as subscriptionId and contactRecordId, for archival and reference purposes. These fields are crucial in preserving historical data linkages and ensuring continuity.
We advise against using these legacy fields for current decision-making or feature development

Detailed Field Descriptions

Basic Information

Name	Type	Description	Example	Applicability	Restrictions
id*	string	Unique identifier for the contact	null (auto-generated)	All	Read Only
assignedUserId	string	Identifier for the user to whom the contact is assigned	bhjT03CtUvWgAy9b3DOQ	Corporate	Read Only
branchId	string	Identifier for the site where the contact is located	br_301	All	Max 64 chars
branchName	string	Name of the site where the contact is located	Tech Support Division	All	Max 128 chars
companyName	string	Name of the company the contact is associated with	8x8 Inc.	Company	Max 128 chars
contactType*	string	Type of contact, e.g., company	company	All	Read Only Enum: company, corporate, service
customerId*	string	Identifier for the customer to whom the contact belongs	0016C00000VM1BeQAX	All	Max 32 chars
department	string	Department within the company where the contact works	Support	Company, Corporate	Max 100 chars
displayWhenNoExtension	boolean	Flag to control visibility of a corporate contact that does not have an extension (i.e. a user with no license). This setting is ignored for corporate contacts that have one more more extensions (extensions[x].displayInDirectory will be used instead)	false	Corporate	Read Only
firstName	string	First name of the contact	Alicia	Company, Corporate	Max 128 chars
jobTitle	string	Professional title of the contact	Account Manager	Corporate	Read Only
lastName	string	Last name of the contact	Rodriguez	Company, Corporate	Max 30 chars
locale	string	Locale setting representing the contact's language and region format	en_US	Company, Corporate	This expects a language code(en-US), or a string representation(en_US)
location	string	Physical or office location of the contact	New York Office	Company	Max 128 chars
middleName	string	Middle name of the contact	B.	Company, Corporate	Max 30 chars
nickName	string	Nickname or informal name used for the contact	Ali	Company, Corporate	Max 30 chars
pbxId	string	Identifier for the PBX associated with the contact	tVK8Vd5Aj1yskcl_-_13A	All	Max 32 chars
pbxName	string	Name of the PBX associated with the contact	voedidionworkflow25	All	Max 32 chars
pictureHash	string	A unique hash value representing the picture, used for verification purposes.	a046a853f0e131f18001d1174d	Company, Corporate	Read Only
subscriptionId	string	Unique identifier for the subscription	0_0qy7cCMFK1HEXLZZA	Service	Read Only
subscriptionName	string	The name of the subscription plan or service	Helpdesk	Service	Read Only
subscriptionType	string	Indicates the service type associated with this extension. It defines which service or functionality the extension is currently linked to or utilizing.	CQ	Service	Read Only Supported Values: UE, VCCE, RG, CQ, AA
subscriptionUserId	string	Identifier for the user associated with the subscription	0eDDyAIIQU1Sb771BB23g	Service	Read Only
timeZone	string	Time zone where the contact is located	America/New_York	Company, Corporate	Accepts region-based zone IDs only (e.g., "America/New_York")

Addresses

Name	Type	Description	Example	Restrictions
apartmentNumber	string	The specific apartment number within a building or complex	102	Max 5 digits
city	string	The city of the contact’s address	San Jose	Max 64 chars
country	string	The nation where the address is located	United States	Max 64 chars
county	string	The county of the contact's address	Santa Clara	Max 64 chars
notes	string	Additional notes about the address	8x8 Headquarters	Max 128 chars
postalCode	string	The postal or ZIP code for the address	95131	Max 16 chars
primary	boolean	Indicates if this is the primary address for the contact	true
purposeType	string	The intended use of the address (e.g., WORK, HOME)	WORK	Supported Values: HOME, WORK, OTHER
state	string	The state or region in which the contact is located	California	Max 64 chars
streetName	string	The name of the street for the address	1st St	Max 64 chars
streetNumber	string	The house or building number	675	Max 8 chars

Emails

Name	Type	Description	Example	Restrictions
email*	string	The email address associated with the contact	[email protected]	Valid email format; must be unique
primary*	boolean	Indicates if this is the primary email address for the contact	true	Only one email can be designated as primary
purposeType*	string	The intended use of the email address	WORK	Supported Values: HOME, WORK, OTHER

Phones

Name	Type	Description	Example	Restrictions
phone*	string	Phone number of the contact. Recommended format: E.164 without punctuation	+18005551234	Valid phone format; must be unique
primary*	boolean	Indicates if this is the primary phone number for the contact	true	Only one phone can be designated as primary
purposeType*	string	The intended use of the phone number	WORK	Supported Values: HOME, HOME_FAX, WORK, WORK_FAX, MOBILE, PAGER, OTHER
source	string	Origin of the phone number	EXTERNAL	Supported Value: EXTERNAL

Name	Type	Description	Example	Restrictions
name*	string	The name or key of the tag	customField1	Limited to 10 values like customField1 through customField10.
value	string	The value assigned to the tag	value1	Max 254 chars

Extensions

Name	Type	Description	Example	Restrictions
branchId	string	Unique identifier for the branch	ovYzzgfDSDqolA3RbhWjbw	Read Only
branchName	string	Name of the branch where the extension is located	DowntownBranch	Read Only
contactId	string	Unique identifier for the associated contact	2h_JNsaISleZWA36GRh3YQ	Read Only
displayInDirectory	boolean	Indicates if the extension is visible in the directory	true	Read Only
extension	string	Extension number	60000001	Read Only
extensionType	string	Indicates whether it is a UC or CC extension	CC	Read Only
fqExtension	string	Fully qualified extension number	1460000001	Read Only
hideInAA	boolean	Flag to hide the contact in the Auto Attendant	true	Read Only
pbxId	string	Unique identifier for the PBX	bhjLT03CTJuVwgAy9y3DOQ	Read Only
pbxName	string	Name of the PBX system associated with the extension	qmsarealenv1	Read Only
subscriptionId	string	Unique identifier for the subscription	aK60JcBERnKIya9Rt7BCxA	Read Only
subscriptionType	string	Type of subscription	UE	Read Only

🚧
Extensions Operational Restrictions
Considered system-generated resources, we restrict modifications to extensions to maintain system integrity.

Visibility Flags Information

Name	Type	Description	Level	Example
displayInDirectory	boolean	Indicates if the extension is visible in the directory	Extension	true
displayWhenNoExtension	boolean	Indicates whether to display the contact when there is no extension number associated	Contact	false
hideInAA	boolean	Determines if the contact should be hidden in the Auto Attendant	Extension	true

Contact Object Structure

📘
Contact Types

Contact JSON Object Structure

🚧
Legacy Field Usage

Detailed Field Descriptions

Basic Information

Addresses

Emails

Phones

Tags

📘
Mandatory Attributes

Extensions

🚧
Extensions Operational Restrictions

Visibility Flags Information

📘Contact Types

Contact JSON Object Structure

🚧Legacy Field Usage

Detailed Field Descriptions

Basic Information

Addresses

Emails

Phones

Tags

📘Mandatory Attributes

Extensions

🚧Extensions Operational Restrictions

Visibility Flags Information

📘
Contact Types

🚧
Legacy Field Usage

📘
Mandatory Attributes

🚧
Extensions Operational Restrictions