Search Contacts

Customers seeking to search for contact information within our Contact Database can use the searchContacts endpoint. Typical use cases include finding contacts based on specific criteria such as name, organization, or other attributes.

πŸ“˜

You will need a working API key to begin

How to get API Keys

For interacting with the Contacts API https://api.8x8.com/contact/api/v3/

1. Obtain API Key for Contact App Product

How to get API Keys

2. Prepare Search Request

Construct your search query using the supported query parameters to filter and sort the contact database.

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
x-api-keyβœ“Pass the API key returned from Admin Console for Contact App productromc_MmFmMTI3sowe
x-cd-filter-by-display-flagXFlag to filter results by display criteriatrue

Query Parameters

NameDescription`Example
detailsDetails needed for contact
Available values : TAG, ADDRESS, PHONE, EMAIL, PICTURE, USER_CONTACT, EXTENSION
PHONE,ADDRESS
filterFiltering capabilities by using Feed Item Query Language (FIQL) filter expressionsfirstName==John
pictureSizeDesired picture size in the returned contacts Available values : ORIGINAL, SMALL, MEDIUM, LARGE, XLARGEORIGINAL
additionalPbxNamesAdditional PBX names to include in searchPBX1, PBX2
additionalBranchIdsAdditional branch IDs to include in searchBranch1, Branch2
Query Parameters Description

Filtering

Contact Object Structure Guide

πŸ“˜

Filtering

This API is designed with filtering capabilities by using Feed Item Query Language (FIQL) filter expressions.
FIQL introduces simple and composite operators which can be used to build basic and complex queries.
If the filter is not specified, All objects are returned.

FIQL Operators:

Equality & Inequality

  • firstName==John β†’ Contacts with first name 'John'.
  • firstName!=John β†’ Contacts without the first name 'John'.

Comparisons

  • createdTimestamp>25 or createdTimestamp=gt=25 β†’ Contacts created after timestamp 25.
  • createdTimestamp>=25 or createdTimestamp=ge=25 β†’ Contacts created at or after timestamp 25.
  • createdTimestamp<25 or createdTimestamp=lt=25 β†’ Contacts created before timestamp 25.
  • createdTimestamp<=25 or createdTimestamp=le=25 β†’ Contacts created at or before timestamp 25.

Inclusion & Exclusion

  • pbxId=in=(US1,US2) β†’ Contacts with pbxId as 'US1' or 'US2'.
  • pbxId=out=(US1) β†’ Contacts excluding those with pbxId as 'US1'.

Logical Operators

  • firstName==John;lastName==Doe β†’ Contacts with first name 'John' AND last name 'Doe'.
  • firstName==John,lastName==Doe β†’ Contacts with first name 'John' OR last name 'Doe'.

Wildcards

  • firstName==Jo* β†’ Contacts with first names starting with 'Jo'.
  • firstName!=*ohn β†’ Contacts with first names not ending with 'ohn'.

The primary sub-objects you can query are:

  • tags: Accessible using fields such as tag.id, tag.name, etc.
  • addresses: Accessible using fields such as address.streetName , address.city , etc.
  • phones: Accessible using fields such as phone.phone, phone.purposeType , etc.
  • emails: Accessible using fields such as email.email , email.purposeType , email.primary, etc
  • extensions: Accessible using fields such as extension.extension, extension.pbxName, extension.pbxId, etc
  • userContact: Accessible using fields such as userContact.userId , userContact.favorite , userContact.contactId

additionalPbxNames

A set of additional PBX names to augment the default search scope. While searches are typically restricted to a specific scope, such as PBX, this parameter allows for the inclusion of extra PBXes to expand the search range.

additionalBranchIds

A set of additional BRANCH ids to augment the default search scope. While searches are typically restricted to a specific scope, such as BRANCH, this parameter allows for the inclusion of extra BRANCH ids to expand the search range.

Pagination Parameters

NameDescriptionTypeExample
useScrollIdIndicates if the scroll ID should be usedBooleantrue
scrollIdID for scrolling through paginated resultsStringWyI3YzA4YW0M2RjYTg2YWRiMzg2MDBkNTZhZCJd
pageThe number of the page to retrieveInteger1
sizeThe size of the page to retrieveInteger10
sortSorting criteria for the search resultsStringname, ASC

Pagination

πŸ“˜

General Note

For offset-based pagination, the sum of "offset + size" in each pagination request is limited to a maximum of 10,000

Keyset pagination

This pagination method implies searching contacts within a key range(keyset) and the usage of this method requires additional parameters:

  • useScrollId=true
  • scrollId=WyI3YzA4YW0M2RjYTg2YWRiMzg2MDBkNTZhZCJd
    • Received in server response, for first request
    • You just need to pass it back as request param for the next request (a different value will be received for each request). This is empty for the first request.
  • size=10&sort=id,ASC
    • It is essential for sorting fields to contain "id" field
    • Additionally, you can also add sorting by other fields - ex "name")

3. Example Usage

Without Pagination

Request

GET https://api.8x8.com/contact/api/v3/contacts?details=TAG,ADDRESS,PHONE,EMAIL,PICTURE,USER_CONTACT,EXTENSION&pictureSize=small&filter=contactType=='corporate';jobTitle=='Agent';[email protected]
Authorization: Bearer {access_token}

πŸ“˜

Request description

The request queries for contacts that are tagged as corporate and have the job title Agent, as well as a specific email [email protected]. It asks for multiple details to be returned for each contact: TAG, ADDRESS, PHONE, EMAIL, PICTURE, USER_CONTACT, and EXTENSION. The request also specifies that the size of the contact pictures should be small.

Response

{
    "data": [
        {
            "id": "2h_JNsaISleZWA36GRh3YQ",
            "customerId": "0016C00000VM1BeQAL",
            "pbxId": "bhjLT03CTJuVwgAy9y3DOQ",
            "pbxName": "qmsarealenv1",
            "branchId": "ovYzzgfDSDqolA3RbhWjbw",
            "branchName": "ContactSite",
            "name": "Contact Agent Test",
            "subscriptionType": null,
            "subscriptionName": null,
            "subscriptionId": null,
            "subscriptionUserId": null,
            "hideInAA": null,
            "contactType": "corporate",
            "assignedUserId": "2h_JNsaISleZWA36GRh3YQ",
            "firstName": "Contact Agent",
            "lastName": "Test",
            "middleName": null,
            "nickName": null,
            "jobTitle": "Agent",
            "department": "Test",
            "companyName": null,
            "timeZone": null,
            "locale": null,
            "location": null,
            "createdTimestamp": 1621341000000,
            "updatedTimestamp": 1678182231575,
            "pictureUrl": null,
            "pictureHash": null,
            "displayWhenNoExtension": true,
            "userContact": null,
            "addresses": [
                {
                    "id": 23071,
                    "country": "Romania",
                    "county": null,
                    "state": null,
                    "city": "Cluj-Napoca",
                    "postalCode": "123456",
                    "streetName": "Buna Ziua 10 Apt 7",
                    "streetNumber": null,
                    "apartmentNumber": null,
                    "notes": null,
                    "purposeType": "OTHER",
                    "primary": true
                }
            ],
            "phones": [
                {
                    "id": 48073,
                    "contactRecordId": null,
                    "phone": "04029511367",
                    "purposeType": "HOME",
                    "primary": false,
                    "source": "EXTERNAL",
                    "subscriptionType": null,
                    "subscriptionId": null
                },
                {
                    "id": 48074,
                    "contactRecordId": null,
                    "phone": "0756124412",
                    "purposeType": "WORK",
                    "primary": false,
                    "source": "EXTERNAL",
                    "subscriptionType": null,
                    "subscriptionId": null
                }
            ],
            "emails": [
                {
                    "id": 86533,
                    "email": "[email protected]",
                    "purposeType": "WORK",
                    "primary": true
                }
            ],
            "tags": [
                {
                    "id": 25672,
                    "name": "customField2",
                    "value": "value2"
                },
                {
                    "id": 25673,
                    "name": "customField1",
                    "value": "value_updated"
                },
                {
                    "id": 25674,
                    "name": "customField3",
                    "value": "value3"
                }
            ],
            "extensions": [
                {
                    "id": 52400,
                    "contactId": "2h_JNsaISleZWA36GRh3YQ",
                    "pbxName": "qmsarealenv1",
                    "pbxId": "bhjLT03CTJuVwgAy9y3DOQ",
                    "branchId": "ovYzzgfDSDqolA3RbhWjbw",
                    "branchName": "ContactSite",
                    "extension": "60000001",
                    "fqExtension": "1460000001",
                    "subscriptionId": "aK60JcBERnKIya9Rt7BCxA",
                    "subscriptionType": "UE",
                    "displayInDirectory": true,
                    "extensionType": "CC"
                }
            ]
        }
    ],
    "meta": {
        "hasMore": false,
        "scrollId": null
    }
}

With Pagination

Initial Request

When you first request a paginated response, you don't have a scrollId yet. The initial request is sent without it:

GET https://api.8x8.com/contact/api/v3/contacts?size=10&sort=id,ASC&useScrollId=true
Authorization: Bearer {access_token}

Initial Response

{
    "data": [
    ],
    "meta": {
        "hasMore": true,
        "scrollId": "WyI2ODA1MDUyZDc1ZjY0N2E5OTQxYzdiYTJjNDU5ODc5OSJd"
    }
}

πŸ“˜

Note

The initial response includes a scrollId, which is necessary for subsequent paginated requests. This ID ensures that the subsequent requests fetch the next set of results in the sequence. Remember to use page=0 in conjunction with scrollId for keyset pagination.

Subsequent Request with scrollId

For the next set of results, you'll use the scrollId provided in the initial response:

GET https://api.8x8.com/contact/api/v3/contacts?page=0&size=10&sort=id,ASC&useScrollId=true&scrollId=WyI2ODA1MDUyZDc1ZjY0N2E5OTQxYzdiYTJjNDU5ODc5OSJd
Authorization: Bearer {access_token}

Subsequent Response

{
    "data": [
    ],
    "meta": {
        "hasMore": true,
        "scrollId": "WyI3YzA4YWM5ZjkxNTU0M2RjYTg2YWRiMzg2MDBkNTZhZCJd"
    }
}