Search Directory Contacts

POST {{baseUrl}}/directories/:directoryId/contacts/search?skipToken=<string>&pageSize=100&includeEmbedded=true&includeSegments=false

Retrieve contacts that satisfy conditions you have specified. <!--From Readme--> You can get the next page of contacts for the filter object by adding the skipToken value returned in the last request to your query params.

If the pageSize is set to 10 and all of the 10 contacts in the previous response were the only contacts that satisfied the specified filter, then the subsequent response when the API call is made with skipToken in previous response will return zero contacts.

If at any time the number of contacts in the response is less than the pageSize, then no skipToken will be included in the response.

Search Depth Limitation

Paginating beyond the first 10,000 contacts will result in a 400 error response.

To return a complete contact list (filtered by your criteria), use the endpoints for Create Contact Export and Get Contact Export File.

Below is a pagination sequence example.

curl 'https://yourdatacenterid.qualtrics.com/API/v3/directories/POOL_DBCF6F11V71CiZx/contacts/search?pageSize=5' \\
-X 'POST' \\
-H 'X-API-TOKEN: yourtokenhere' \\
-H 'Content-Type: application/json' \\
-d '
     {
       "filter": {
         "comparison": "eq",
         "filterType": "lastName",
         "value": "test"
       }
     }
   '

curl 'https://yourdatacenterid.qualtrics.com/API/v3/directories/POOL_DBCF6F11V71CiZx/contacts/search?pageSize=5&skipToken=NQ==' \\
-X 'POST' \\
-H 'X-API-TOKEN: yourtokenhere' \\
-H 'Content-Type: application/json' \\
-d '
     {
       "filter": {
         "comparison": "eq",
         "filterType": "lastName",
         "value": "test"
       }
     }
   '

curl 'https://yourdatacenterid.qualtrics.com/API/v3/directories/POOL_DBCF6F11V71CiZx/contacts/search?pageSize=5&skipToken=MTA=' \\
-X 'POST' \\
-H 'X-API-TOKEN: yourtokenhere' \\
-H 'Content-Type: application/json' \\
-d '
     {
       "filter": {
         "comparison": "eq",
         "filterType": "lastName",
         "value": "test"
       }
     }
   '

{
  "result": {
    "elements": [
      {
        "id": "CID_XXXXXXXXXXXX001",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX002",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX003",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX004",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX005",
        ...
      },
    ],
    "skipToken": "NQ=="
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "ae8f9d62-217b-4f98-89f8-94fb2b43dcc7"
  }
}

{
  "result": {
    "elements": [
      {
        "id": "CID_XXXXXXXXXXXX006",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX007",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX008",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX009",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX010",
        ...
      },
    ],
    "skipToken": "MTA="
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "0dd60d0d-4d43-4937-b278-b0b085c6cbca"
  }
}

{
  "result": {
    "elements": [
      {
        "id": "CID_XXXXXXXXXXXX011",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX012",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX013",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX014",
        ...
      },
      {
        "id": "CID_XXXXXXXXXXXX015",
        ...
      },
    ],
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "1bd55949-0aa4-4533-9c8e-fc897b90c237"
  }
}

Filter Criterion

Below are the supported filter criteria and their associated JSON syntax.

Leading and trailing spaces

String values associated with JSON keys that are not filterType or comparison will have any leading and trailing spaces trimmed off.

The JSON keys filterType and comparison have strict values enumerated herein. Any deviation from those values will result in an error being returned in the API response.

Filter Conjunction

The filter conjunction allows one to combine multiple criteria to retrieve contacts from the directory with precision.

Field 'conjunction': 'and' need to be added as an attribute inside filter to show that multiple filters need to be combined. The number of filters should be ranged from 2 to 5. If more than 5 filters are combined, an error will be thrown.

numericComparison

JSON data type: string

Valid values are: - eq - neq - gt - lt - gte - lte

Value represents a date must match the format yyyy-MM-dd or yyyy-MM-dd hh:mm:ss

stringComparison

JSON data type: string Valid values are: - eq - neq

String comparison is not case sensitive for the values it is inspecting. sEArcH is equivalent to search, SEARCH, SeaRCh and so on...

Request Params

Request Body

{"filter"=>{"culpabd"=>53553139}}

HEADERS

RESPONSES

status: OK

{"result":{"elements":[{"id":"CID_012345678901234","creationDate":"ex dolor","lastModified":"cillum velit Ut","firstName":"Jane","lastName":"Doe","email":"JaneDoe@email.com","phoneNumber":"111-111-1111","externalDataReference":"my_Internal_ID_12345","language":"","unsubscribed":false,"unsubscribeDate":"do voluptate proident","stats":{"dolor3":"esse irure amet","eiusmod_c2":"in magna veniam ad velit","sint__c":"sit deserunt laborum esse","inf50":"labore minim qui consectetur","velit0":"do occaecat veniam incididunt"},"embeddedData":{"est7f":"anim enim adipisicing","anim_61":"eu mollit es","aute_90":"Ut sed proident","tempor_b":"minim"},"segmentMembership":{"exercitation87":{"contactLookupId":"quis nulla id","ownerId":"adipisicing in veli","unsubscribed":true,"unsubscribedDate":"1981-08-30T14:13:33.958Z","name":"occaecat consequat dolore deserunt"},"laborisd0d":{"contactLookupId":"fugiat incididunt","ownerId":"quis mollit aute ipsum","unsubscribed":false,"unsubscribedDate":"1983-05-28T02:14:32.235Z","name":"ullamco veniam ut nostrud deserunt"}}},{"id":"CID_012345678901234","creationDate":"mollit","lastModified":"non aliquip voluptate","firstName":"Jane","lastName":"Doe","email":"JaneDoe@email.com","phoneNumber":"111-111-1111","externalDataReference":"my_Internal_ID_12345","language":"","unsubscribed":true,"unsubscribeDate":"Ut ut deserunt sunt pariatur","stats":{"nostrud_daf":"cupidatat Duis eius"},"embeddedData":{"nostrud41":"culpa","in_9a0":"do cillum esse adipisicing ullamco","anim8f":"ex occaecat laboris laborum"},"segmentMembership":{"reprehenderit_e":{"contactLookupId":"anim velit Lorem esse do","ownerId":"adipisicing irure id","unsubscribed":true,"unsubscribedDate":"1986-10-28T13:38:10.503Z","name":"minim aliqua Excepteur Ut ex"},"do3d1":{"contactLookupId":"aute ut","ownerId":"laboris","unsubscribed":false,"unsubscribedDate":"1983-09-11T20:27:28.549Z","name":"ad aliquip"},"velit1":{"contactLookupId":"consequat do","ownerId":"anim pariatur eu nisi","unsubscribed":true,"unsubscribedDate":"1952-07-22T19:44:24.241Z","name":"magna labore in"},"adipisicing_383":{"contactLookupId":"amet","ownerId":"irure","unsubscribed":true,"unsubscribedDate":"2007-02-25T11:32:06.467Z","name":"proident occaecat deserunt Ut"}}}],"skipToken":"\u003cstring\u003e"},"meta":{"httpStatus":"voluptate irure dolore","requestId":"amet sed cillum aliqua","notice":"aute enim exercitation"}}