Contact
  • 27 Jul 2023
  • 8 Minutes to read
  • Dark
    Light

Contact

  • Dark
    Light

Article Summary

Contact

Contact JSON Format

Contact is represented as simple flat JSON objects with the following keys:

NameTypeDescription
idguidId of the contact.
namestringName of the contact.
firstNamestringFirst name of the contact.
lastNamestringLast name of the contact.
createTimedatetimeWhen the contact was created.
lastUpdatedTimedatetimeThe time of the last update time.
mergeToContactIdguidContact id which the contact merged to.
customFieldsContact Custom Field ValueCustom field value.
contactIdentitiescontactIdentities[]TReference to Contact identity.

Contact Identity Object

Contact Identity is represented as simple flat JSON objects with the following keys:

NameTypeDescription
idguidId of the contact identity.
typestringAllowed values are visitor, Email, SMS, facebook, twitter, wechat, SSOID, externalID, whatsApp, instagram, telegram, line, SecureMessaging.
valuestringThe value of the identity.
avatarstringThe avatar used in a certain channel, like the avatar of a Facebook user. Not every channel yields an avatar. For example, SMS Numbers will not produce one.
identityInfoUrlstringContact information from the channels. Such as the number of Twitter followers and tweets from the twitter identity. The info is displayed in an iframe in the agent console. Available for Twitter, Facebook, SMS, and WeChat.
originalContactPageUrlstringThe contact profile URL on Facebook or Twitter.
displayNamestringThe name of identity.

Contact Filter Condition Object

Contact Filter Condition is represented as simple flat JSON objects with the following keys:

NameTypeDescription
fieldNamestringField name of the contact filter condition.
operatorstringAllowed values are "Contains", "Does Not Contain", "Is", "Is Not", "Is More Than", "Is Less Than", "Before", "After".
valuestringTrigger mode of the contact filter condition.
orderintegerOrder of the contact filter condition.

Contact custom field value object

NameTypeDescription
namestringName of the custom field.
valuestringValue of the custom field.

Get the list of Contact

GET /contact/contacts

  • Parameters

    NameTypeinRequiredDescription
    keywordsstringquerynoSearch scope includes: contact name, identity id, identity value.
    contactIdentityTypestringquerynoType of the contact identity. Allowed values are visitor, Email, SMS, facebook, twitter, wechat, SSOID, externalID, whatsApp, instagram, telegram, line, SecureMessaging.
    contactIdentityValuestringquerynoValue of the contact identity.
    isIncludeDeletedboolquerynoWhether including the deleted contact or not, default value: false.
    pageIndexintegerquerynoPage index.
    pageSizeintegerquerynoPage size, default is 50, and the value can not be larger than 500.
    sortBystringquerynoSort by.
    sortOrderstringquerynoAllowed values are asc,desc, default asc.
  • Response

The array of Contact.

  • Example

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts   \ 
    -X 'GET' \ 
    -H 'Authorization: Bearer {access_token}' \ 

Response:

HTTP/1.1 200 OK

{
    "contacts": [
        {
            "id": "6396ad99-6885-4489-ad95-43c923154a8c",
            "contactIdentities": [
                {
                    "id": "9bf5f300-a8b0-4dd9-996d-140fe87c851e",
                    "contactId": "6396ad99-6885-4489-ad95-43c923154a8c",
                    "contactIdentityType": "Email",
                    "value": "testContact@gmail.com",
                    "avatarUrl": "",
                    "infoUrl": "",
                    "displayName": "testContact@gmail.com",
                    "originalContactPageUrl": "",
                    "isDeleted": false
                },
                {
                    "id": "5a1900c6-8329-4d00-86ed-697cdfaa9e8b",
                    "contactId": "6396ad99-6885-4489-ad95-43c923154a8c",
                    "contactIdentityType": "SMS",
                    "value": "+11111111",
                    "avatarUrl": "",
                    "infoUrl": "",
                    "displayName": "+11111111",
                    "originalContactPageUrl": "",
                    "isDeleted": false
                }
            ],
            "lastName": "Last name for test",
            "firstName": "Firstname for test",
            "name": "testContact",
            "mergeToContactId": "00000000-0000-0000-0000-000000000000",
            "createTime": "2022-09-02T04:12:40Z",
            "lastUpdatedTime": "2022-09-02T04:12:40Z",
            "customFields": {
                "description": "",
                "alias": "",
                "title": "",
                "company": "",
                "fax": "",
                "phone": "",
                "mailingaddress": "",
                "city": "",
                "stateorprovince": "",
                "countryorregion": "",
                "postalorzipcode": "",
                "timezone": ""
            },
            "isDeleted": false
        }
    ],
    "previousPage": null,
    "nextPage": null,
    "total": 1
}

Query contact with conditions

POST /contact/contacts:query

  • Parameters

    NameTypeinRequiredDescription
    pageIndexintegerquerynoPage index.
    pageSizeintegerquerynoPage size, default is 50, and the value can not be larger than 500.
    sortBystringquerynoSort by.
    sortOrderstringquerynoAllowed values are asc,desc, default asc.
    keywordsstringbodynoSearch scope includes: contact name, identity id, identity value.
    contactIdentityTypestringbodynocontact identity type.
    filterConditionMetTypestringbodynoContact Filter Logical Expresssion of this Condition. Allowed values are All, Any, LogicalExpression.
    filterLogicalExpresssionstringbodynoContact Filter Logical Expression.
    filterConditionsContactFilterCondition object[]bodynoAn array of ContactFilterCondition object
    IdsarraybodynoContact Ids array, if pass this parameter, the keywords and filter conditions don't work.
    isIncludeDeletedboolbodynoWhether including the deleted contact or not, default value: false.
  • Response

The array of Contact.

  • Example

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts:query  \ 
    -X 'POST' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -D '{"keywords": "test","contactIdentityType": "SMS","filterConditionMetType": "All","filterLogicalExpresssion": "",  "filterConditions": [],"Ids": "", "isIncludeDeleted": false }'

Response:

HTTP/1.1 200 OK

{
    "contacts": [
        {
            "id": "6396ad99-6885-4489-ad95-43c923154a8c",
            "contactIdentities": [
                {
                    "id": "9bf5f300-a8b0-4dd9-996d-140fe87c851e",
                    "contactId": "6396ad99-6885-4489-ad95-43c923154a8c",
                    "contactIdentityType": "Email",
                    "value": "testContact@gmail.com",
                    "avatarUrl": "",
                    "infoUrl": "",
                    "displayName": "testContact@gmail.com",
                    "originalContactPageUrl": "",
                    "isDeleted": false
                },
                {
                    "id": "5a1900c6-8329-4d00-86ed-697cdfaa9e8b",
                    "contactId": "6396ad99-6885-4489-ad95-43c923154a8c",
                    "contactIdentityType": "SMS",
                    "value": "+11111111",
                    "avatarUrl": "",
                    "infoUrl": "",
                    "displayName": "+11111111",
                    "originalContactPageUrl": "",
                    "isDeleted": false
                }
            ],
            "lastName": "Last name for test",
            "firstName": "Firstname for test",
            "name": "testContact",
            "mergeToContactId": "00000000-0000-0000-0000-000000000000",
            "createTime": "2022-09-02T04:12:40Z",
            "lastUpdatedTime": "2022-09-02T04:12:40Z",
            "customFields": {
                "description": "",
                "alias": "",
                "title": "",
                "company": "",
                "fax": "",
                "phone": "",
                "mailingaddress": "",
                "city": "",
                "stateorprovince": "",
                "countryorregion": "",
                "postalorzipcode": "",
                "timezone": ""
            },
            "isDeleted": false
        }
    ],
    "previousPage": null,
    "nextPage": null,
    "total": 1
}

Get a single Contact

GET /contact/contacts/{id}

  • Parameters

    NameTypeinRequiredDescription
    idguidpathyesId of the Contact.
    isIncludeDeletedboolquerynoWhether including the deleted contact or not, default value: false.
  • Response

Contact

  • Example

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts/6396ad99-6885-4489-ad95-43c923154a8c \ 
    -X 'GET' \ 
    -H 'Authorization: Bearer {access_token}' \ 

Response:

HTTP/1.1 200 OK

 {
    "id": "6396ad99-6885-4489-ad95-43c923154a8c",
    "contactIdentities": [
        {
            "id": "9bf5f300-a8b0-4dd9-996d-140fe87c851e",
            "contactId": "6396ad99-6885-4489-ad95-43c923154a8c",
            "contactIdentityType": "Email",
            "value": "testContact@gmail.com",
            "avatarUrl": "",
            "infoUrl": "",
            "displayName": "testContact@gmail.com",
            "originalContactPageUrl": "",
            "isDeleted": false
        },
        {
            "id": "5a1900c6-8329-4d00-86ed-697cdfaa9e8b",
            "contactId": "6396ad99-6885-4489-ad95-43c923154a8c",
            "contactIdentityType": "SMS",
            "value": "+11111111",
            "avatarUrl": "",
            "infoUrl": "",
            "displayName": "+11111111",
            "originalContactPageUrl": "",
            "isDeleted": false
        }
    ],
    "lastName": "Last name for test",
    "firstName": "Firstname for test",
    "name": "testContact",
    "mergeToContactId": "00000000-0000-0000-0000-000000000000",
    "createTime": "2022-09-02T04:12:40Z",
    "lastUpdatedTime": "2022-09-02T04:12:40Z",
    "customFields": {
        "description": "",
        "alias": "",
        "title": "",
        "company": "",
        "fax": "",
        "phone": "",
        "mailingaddress": "",
        "city": "",
        "stateorprovince": "",
        "countryorregion": "",
        "postalorzipcode": "",
        "timezone": ""
    },
    "isDeleted": false
}

Create a new Contact

POST /contact/contacts

  • Parameters

    NameTypeinRequiredDescription
    namestringbodyyesThe name of the Contact.
    firstNamestringbodynoFirst name of the contact.
    lastNamestringbodynoLast name of the contact.
    contactIdentitycontactIdentities[]bodyyesThe array of Contact identitiy.
    customFieldcustom fieldsbodynoValue of contact custom fields.
  • Response

Contact

  • Example:

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts \ 
    -X 'POST' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -H 'Content-Type: application/json' \
    -D '{"name": "testContact6","contactIdentities": [{"contactIdentityType": "Email","value": "testContact6@gmail.com"}]}'

Response:

HTTP/1.1 200 OK

  {
    "id": "f20ac8fb-f040-4fe4-a426-7592b1f9f743",
    "contactIdentities": [
        {
            "id": "5724e782-b5bc-4b83-8aee-2356548ada73",
            "contactId": "f20ac8fb-f040-4fe4-a426-7592b1f9f743",
            "contactIdentityType": "Email",
            "value": "testContact6@gmail.com",
            "avatarUrl": "",
            "infoUrl": "",
            "displayName": "testContact6@gmail.com",
            "originalContactPageUrl": "",
            "isDeleted": false
        }
    ],
    "lastName": "fristname for test 6",
    "firstName": "last name for test 6",
    "name": "testContact6",
    "mergeToContactId": "00000000-0000-0000-0000-000000000000",
    "createTime": "2022-09-02T04:48:47Z",
    "lastUpdatedTime": "2022-09-02T04:48:47Z",
    "customFields": {
        "description": "",
        "alias": "",
        "title": "",
        "company": "",
        "fax": "",
        "phone": "",
        "mailingaddress": "",
        "city": "",
        "stateorprovince": "",
        "countryorregion": "",
        "postalorzipcode": "",
        "timezone": ""
    },
    "isDeleted": false
}
  • Example:

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts \ 
    -X 'POST' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -H 'Content-Type: application/json' \
    -D '{
    "name": "testing2",
    "description": "",
    "firstName": "TT",
    "lastName": "LAST",
    "alias": "",
    "title": "C1",
    "company": "",
    "fax": "",
    "phone": "",
    "mailingAddress": "",
    "city": "Changsha",
    "stateOrProvince": "Hunan",
    "countryOrRegion": "",
    "postalOrZipCode": "",
    "createTime": "2021-05-09T07:42:02.2966667Z",
    "lastUpdatedTime": "2021-05-09T07:42:02.2966667Z",
    "mergeToContactId": "00000000-0000-0000-0000-000000000000" ,
   "contactIdentities":[
        {
            "displayName":"fengchufu",
            "value":"+111111112",
            "avatarUrl":"",
            "infoUrl":"",
            "originalContactPageUrl":"",
            "contactIdentityType":"SMS"
        }
    ],
    "customFields":{
        "description":"fengchufu",
        "phone":"123",
        "fax":"123",
        "alias":"",
        "title":"test",
        "company":"",
        "mailingaddress":"test@163.com",
        "city":"",
        "stateorprovince":"NewYork",
        "countryorregion":"America",
        "postalorzipcode":"",
        "timezone":"UTC-11",
        "ss":"",
        "test_ddp":"Example A"
    }
}'

Response:

HTTP/1.1 200 OK

  {
    "id": "4537ba81-1652-4654-b341-5851bf5adaf0",
    "contactIdentities": [
        {
            "id": "425d3c6f-442c-ee11-998a-00155de0e60a",
            "contactId": "4537ba81-1652-4654-b341-5851bf5adaf0",
            "contactIdentityType": "SMS",
            "value": "+111111112",
            "avatarUrl": "",
            "infoUrl": "",
            "displayName": "fengchufu",
            "originalContactPageUrl": "",
            "isDeleted": false
        }
    ],
    "lastName": "LAST",
    "firstName": "TT",
    "name": "testing2",
    "mergeToContactId": "00000000-0000-0000-0000-000000000000",
    "createTime": "2023-07-27T06:11:34Z",
    "lastUpdatedTime": "2023-07-27T06:11:34Z",
    "customFields": {
        "description": "fengchufu",
        "alias": "",
        "title": "test",
        "company": "",
        "fax": "123",
        "phone": "123",
        "mailingaddress": "test@163.com",
        "city": "",
        "stateorprovince": "NewYork",
        "countryorregion": "America",
        "postalorzipcode": "",
        "timezone": "UTC-11"
    },
    "isDeleted": false
}

Update the Contact

PUT /contact/contacts/{id}

  • Parameters

    NameTypeinRequiredDescription
    idguidpathyesThe unique id of the Contact
    namestringbodyyesThe name of the Contact.
    firstNamestringbodynoFirst name of the contact.
    lastNamestringbodynoLast name of the contact.
    contactIdentitycontactIdentities[]bodyyesThe array of Contact identitiy.
    customFieldcustom fieldsbodynoValue of contact custom fields.
  • Response

Contact

  • Example:

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts/f20ac8fb-f040-4fe4-a426-7592b1f9f743 \ 
    -X 'PUT' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -H 'Content-Type: application/json' \ 
    -D '{"name": "newContact6","lastName": "fristname for test 6","firstName": "last name for test 6","contactIdentities": [{"contactId": "f20ac8fb-f040-4fe4-a426-7592b1f9f743","contactIdentityType": "Email","value": "newContact6@gmail.com","avatarUrl": "","infoUrl": "","displayName": "newContact6@gmail.com","originalContactPageUrl": ""}]}'

Response:

HTTP/1.1 200 OK

{
    "id": "f20ac8fb-f040-4fe4-a426-7592b1f9f743",
    "contactIdentities": [
        {
            "id": "5724e782-b5bc-4b83-8aee-2356548ada73",
            "contactId": "f20ac8fb-f040-4fe4-a426-7592b1f9f743",
            "contactIdentityType": "Email",
            "value": "newContact6@gmail.com",
            "avatarUrl": "",
            "infoUrl": "",
            "displayName": "newContact6@gmail.com",
            "originalContactPageUrl": "",
            "isDeleted": false
        }
    ],
    "lastName": "fristname for test 6",
    "firstName": "last name for test 6",
    "name": "newContact6",
    "mergeToContactId": "00000000-0000-0000-0000-000000000000",
    "createTime": "2022-09-02T04:48:47Z",
    "lastUpdatedTime": "2022-09-02T04:58:55Z",
    "customFields": {
        "description": "",
        "alias": "",
        "title": "",
        "company": "",
        "fax": "",
        "phone": "",
        "mailingaddress": "",
        "city": "",
        "stateorprovince": "",
        "countryorregion": "",
        "postalorzipcode": "",
        "timezone": ""
    },
    "isDeleted": false
}

Delete the Contact

DELETE /contact/contacts/{id}

  • Parameters

No Parameters

  • Response

No Content

  • Example

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts/f20ac8fb-f040-4fe4-a426-7592b1f9f743 \ 
    -X 'DELETE' \ 
    -H 'Authorization: Bearer {access_token}' \ 

Response:

HTTP/1.1 204 No Content

Batch delete contacts

DELETE /contact/contacts

  • Parameters

    NameTypeinRequiredDescription
    idsarraybodyyesThe array of the contact id.
  • Response

No Content

  • Example

Sample Request:

curl https://api11.comm100.io/v4/contact/contacts \ 
    -X 'DELETE' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -H 'Content-Type: application/json' \ 
    -D '["59114fff-0eda-4418-8dd2-229a8b784c44","4e851d92-72ca-4b6b-96b0-7184e96413b2"]'

Response:

HTTP/1.1 204 No Content


Was this article helpful?

What's Next