Contacts

Number of APIs: 11

The Contacts API allows you to create and manage the contacts to whom you will send your surveys.

Workflows

• Create Contact
• List Contacts
• Get Contact
• Get Contact History
• Update Contact
• Delete Contact

Code and Qualtrics Support

Our support team does not offer assistance or consultation on custom coding, but you can always try asking our community of dedicated users. If you’d like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.

XM Directory Only

These APIs are only available to XM Directory users.

Create Contact

The Create Contact API allows you to create new contacts in the XM Directory directory. Contacts are made up of at least the standard contact data of first name, last name, email address, phone number and language. In addition to these basic fields, you can include data from your internal systems to help you identify and manage your contacts more easily.

In the extRef field, you can add an ID from your internal systems, which provides you the ability to cross-reference your contact list with the list you have in Qualtics' system. This is any alphanumeric ID, and should be unique per individual

Contacts can also include an arbitrary (defined by you) data object in the embeddedData field. You can use this to add information about your contact to customize the user experience per contact.

curl --location --request POST 'st3.qualtrics.com/API/v3/directories/POOL_012345678901234/contacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 194da047-9099-4893-8edb-e52bca0e60d6' \
--data-raw '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "JaneDoe@email.com",
    "phone": "111-111-1111",
    "extRef": "my_Internal_ID_12345",
    "embeddedData": { "level": "mid", "area": "coast" },
    "language": "",
    "unsubscribed": false
}'

A successful call will receive a response like the one below, which provides you the contact ID of the newly created contact:

{
  "result": {
    "id": "CID_012345678901234"
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "900df19-75fd-479d-b4c2-6fd1f4b7b3e0"
  }
}

List Contacts

Once you've created one or more contacts in your directory, you can list those contactsw using the List Contacts API. This API lists the current contents of the XM Directory directory.

Your contact lists can grow large, and will likely require you to paginate through the data. Ther are two ways to do this. 1) Use the pageSize and offset parameters, or 2) Repeatedly call this API using the nextPage value until nextPage is null

To use the pageSize and offset parameters, make calls like the one below, and increment the offset with each call:

curl --location --request GET 'st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts?pageSize=2&offset=3' \
--header 'Authorization: Bearer 4713af3c-a39d-4c54-adbf-863b4e8ac685'

If you want to use the nextPage value, make the first call then grab the nextPage

curl --location --request GET 'st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts?pageSize=2' \
--header 'Authorization: Bearer 4713af3c-a39d-4c54-adbf-863b4e8ac685'

This will return a result that looks like this:

{
    "result": {
        "elements": [
            {
                "contactId": "CID_018xUkJgOCcpy6x",
                "firstName": "First123w3",
                "lastName": "Last123r3",
                "email": "firstLast@example.com",
                "phone": "",
                "extRef": "Example",
                "language": "",
                "unsubscribed": true
            },
            {
                "contactId": "CID_01bVky8E0pU4Nwh",
                "firstName": "First123w149",
                "lastName": "Last123r149",
                "email": "firstlast+149@example.com",
                "phone": "",
                "extRef": "Example",
                "language": "",
                "unsubscribed": true
            }
        ],
        "nextPage": "https://g1-iad.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts?pageSize=2&skipToken=CID_01bVky8E0pU4Nwh"
    },
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "4cb5780c-783c-4358-8184-6f944ee42200"
    }
}

When you get that result, read in the nextPage field from the result, and feed it into your next call (including authentication) like so:

curl --location --request GET 'https://g1-iad.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts?pageSize=2&skipToken=CID_01bVky8E0pU4Nwh' \
--header 'Authorization: Bearer 4713af3c-a39d-4c54-adbf-863b4e8ac685'

Continue calling the 'nextPage' URL until the nextPage field returns null, indicating the end fo the list.

Embedded Data

The List Contacts API does not return the embedded data for each contact. You need to call Get Contact on each contact for which you wish to obtain their embedded data.

Get Contact

The Get Contact API returns extensive information about a contact. The information includes metadata about the contact (such as first name), embedded data, and statistics about the contact's survey responses and email interactions.

curl --location --request GET 'st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts/CID_0HTHRaqN6r36dZX' \
--header 'Authorization: Bearer cb5e8940-be5f-46e9-992b-bd2d4d33197d'

{
    "result": {
        "contactId": "CID_0HTHRaqN6r36dZX",
        "creationDate": 1576438392000,
        "lastModified": 1576438392000,
        "firstName": "John",
        "lastName": "Smith",
        "email": "person@example.com",
        "emailDomain": "example.com",
        "phone": "",
        "language": "",
        "writeBlanks": false,
        "extRef": "Example",
        "embeddedData": {},
        "transactionData": [],
        "stats": {
            "AvgTimeToRespond": null,
            "DataIntegrity": "100",
            "EmailCount": "0",
            "InviteCount": "0",
            "LastEmailDate": null,
            "LastInviteDate": null,
            "LastResponseDate": null,
            "MonthEmailCount": "0",
            "MonthInviteCount": "0",
            "Points": "0",
            "ResponseCount": "0",
            "ResponseRate": "0.0"
        },
        "skipped": null,
        "directoryUnsubscribed": true,
        "directoryUnsubscribeDate": 1576438392000,
        "mailingListMembership": {
            "CG_er1pwJbK9BZuxo1": {
                "contactLookupId": "CGC_0Sq6nDxkHoY025n",
                "name": "My Contact List",
                "unsubscribed": true,
                "unsubscribeDate": 1576438393000,
                "ownerId": "UR_cVcNH0elQesua8J"
            }
        }
    },
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "7a5f1ae3-ce51-405d-804d-e26315bc2553"
    }
}

Get Contact History

The Get Contact History API returns information about either the emails sent to a contact or the survey responses supplied by a contact. The type query parameter specifies the type of history to return. The following code example demonstrates how to return a contact's survey response history (type is set to email).

curl --location --request GET 'st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts/CID_0HTHRaqN6r36dZX/history?type=email&offset=0&pageSize=100' \
--header 'Authorization: Bearer 7fcb1a22-5618-4466-a933-097293505f03'

The returned objects contain extensive histories of the contact's interactions with the Qualtrics system. For detailed information on the what details the returned objects contain, see Get Contact History

The following response object shows the contact's email history (with type set to email):

{
              "elements": [
                {
                  "distributionId": "EMD_1234567890abcde",
                  "date": "2015-04-09 19:42:29",
                  "type": "Invite",
                  "result": "Success",
                  "surveyId": "SV_1234567890abcde",
                  "read": true
                },
                {
                  "distributionId": "EMD_1234567890abcdf",
                  "date": "2015-04-09 19:42:29",
                  "type": "Invite",
                  "result": "Bounce",
                  "bounceInfo": {
                    "type": "Hard"
                  },
                  "surveyId": "SV_1234567890abcde",
                  "read": false
                }
              ],
              "nextPage": null
            },
            "meta": {
              "httpStatus": "200 - OK"
            }
          }

The following response object shows the contact's response history (when type is set to response):

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "607a5061-6ba7-4014-875d-7da1315c61a2"
    },
    "result": {
        "elements": [
            {
                "distributionId": "EMD_5vdjLiUJT1JATop",
                "responseId": "R_qFxoeiLscvMneff",
                "surveyCompletedDate": "2017-08-08 14:58:57",
                "surveyFinished": true,
                "surveyId": "SV_cBjbWZ2uyPIQVLf",
                "surveyStartedDate": "2017-08-08 14:58:53"
            },
            {
                "distributionId": "EMD_9odFkKG1Cdflln7",
                "responseId": "R_2wvOxMidyyh7ZKb",
                "surveyCompletedDate": "2017-08-17 20:52:29",
                "surveyFinished": true,
                "surveyId": "SV_8pivLTQNqPohG5v",
                "surveyStartedDate": "2017-08-17 20:52:18"
            },
            {
                "distributionId": "EMD_eanPyQa5ondBhkN",
                "responseId": "R_rfjAlFwK65ZsNYR",
                "surveyCompletedDate": "2017-08-17 22:32:27",
                "surveyFinished": true,
                "surveyId": "SV_6hZDPZroTErKGZD",
                "surveyStartedDate": "2017-08-17 22:32:16"
            },
            {
                "distributionId": "EMD_eXog2zBKVo9Fpnn",
                "responseId": "R_b8vRD49BdnI4Pct",
                "surveyCompletedDate": "2017-09-04 19:36:57",
                "surveyFinished": true,
                "surveyId": "SV_9ukvzzzAdLsjLq5",
                "surveyStartedDate": "2017-09-04 19:36:43"
            },
            {
                "distributionId": null,
                "responseId": "R_1eM2NjAkNoH08mx",
                "surveyCompletedDate": "2017-09-04 19:55:47",
                "surveyFinished": true,
                "surveyId": "SV_9ukvzzzAdLsjLq5",
                "surveyStartedDate": "2017-09-04 19:55:48"
            }
        ],
        "nextPage": null
    }
}

Update Contact

The Update Contact API allows you to change existing metadata for a contact. You can also add or update a contact's embedded data.

The example below shows how to update a contact's information to include an external reference and add embedded data. Note the request only includes the fields needing updates, the other fields will retain previous values.

curl --location --request PUT 'st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts/CID_0HTHRaqN6r36dZX' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 7fcb1a22-5618-4466-a933-097293505f03' \
--data-raw '{
    "extRef": "my_Internal_ID_12345",
    "embeddedData": { "myField1": "data from my system", "myField2": "more data from my system"}
}'

This will receive a response like:

{
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "900df19-75fd-479d-b4c2-6fd1f4b7b3e0"
  }
}

Once your update is complete, if you call Get Contact, you will see the result of your update, as below:

{
    "result": {
        "contactId": "CID_0HTHRaqN6r36dZX",
        "creationDate": 1576438392000,
        "lastModified": 1614115197000,
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "janedoe@example.com",
        "emailDomain": "example.com",
        "phone": "",
        "language": "",
        "writeBlanks": false,
        "extRef": "my_Internal_ID_12345",
        "embeddedData": {
            "myField1": "data from my system",
            "myField2": "more data from my system"
        },
        "transactionData": [],
        "stats": {
            "AvgTimeToRespond": null,
            "DataIntegrity": "100",
            "EmailCount": "0",
            "InviteCount": "0",
            "LastEmailDate": null,
            "LastInviteDate": null,
            "LastResponseDate": null,
            "MonthEmailCount": "0",
            "MonthInviteCount": "0",
            "Points": "0",
            "ResponseCount": "0",
            "ResponseRate": "0.0"
        },
        "skipped": null,
        "directoryUnsubscribed": true,
        "directoryUnsubscribeDate": 1576438392000,
        "mailingListMembership": {
            "CG_er1pwJbK9BZuxo1": {
                "contactLookupId": "CGC_0Sq6nDxkHoY025n",
                "name": "Test Contact List",
                "unsubscribed": true,
                "unsubscribeDate": 1576438393000,
                "ownerId": "UR_cVcNH0elQesua8J"
            }
        }
    },
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "bebc23ea-8a03-4b67-9f5e-87a0c52a3f07"
    }
}

Delete Contact

The Delete Contact API allows you to permanently delete a contact from the organization's directory. The example below shows how to use this API:

curl --location --request DELETE 'st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/contacts/CID_0HTHRaqN6r36dZX' \
--header 'Authorization: Bearer 7fcb1a22-5618-4466-a933-097293505f03'

A successful delete results in a 200 status code. An example response is shown below:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "1702483a-ced4-40a5-9ade-20e01475055b"
    }
}

© 2020 Qualtrics, LLC

Contact Support: Name: Support

1. directories/{directoryId}-contacts - Create Directory Contact POST {{baseUrl}}/directories/:directoryId/contacts

2. directories/{directoryId}-contacts-{contactId} - Delete Directory Contact DELETE {{baseUrl}}/directories/:directoryId/contacts/:contactId

3. directories/{directoryId}-contacts-{contactId} - Get Directory Contact History GET {{baseUrl}}/directories/:directoryId/contacts/:contactId/history?type=email&offset=0&pageSize=100

4. directories/{directoryId}-contacts-{contactId} - Get Directory Contact GET {{baseUrl}}/directories/:directoryId/contacts/:contactId

5. directories/{directoryId}-contacts-{contactId} - Update Directory Contact PUT {{baseUrl}}/directories/:directoryId/contacts/:contactId

6. directories/{directoryId}-contacts - List Directory Contacts GET {{baseUrl}}/directories/:directoryId/contacts?pageSize=100&skipToken=qui

7. directories/{directoryId}-contacts - List Opted Out Directory Contacts GET {{baseUrl}}/directories/:directoryId/contacts/optedOutContacts?pageSize=100&since=2022-01-01T00:00:00.00Z&skipToken=<string>

8. directories/{directoryId}-contacts - Search Directory Contacts POST {{baseUrl}}/directories/:directoryId/contacts/search?skipToken=<string>&pageSize=100&includeEmbedded=true&includeSegments=false

9. directories/{directoryId}-export-contacts - Create Contact Export POST {{baseUrl}}/directories/:directoryId/export-contacts

10. directories/{directoryId}-export-contacts - Get Contact Export Progress Status GET {{baseUrl}}/directories/:directoryId/export-contacts/:progressId/status