Table of Contents:
Table of Contents minLevel 2
Note: Notice that in each API call you must provide the List ID that you are working on, otherwise the default List ID will be used.
Methods Summary
This API controller is for managing asynchronous contact searches.
...
Create instance - Create a new contact search using "POST api/contact_search" You need to set a title for this new search, and the filters used for contacts segmentation.
Check the instance status - Check the contact search status using "GET api/contact_search/<Contact search report ID>" When contact search is created, its always created in status "Pending" (1), in order to know when the contact search is ready, use this method and verify that the status is "Completed" (2).
Get the instance results - When status is Complete, get results using "GET api/contact_search/<Contact search report ID>/result" This will return an array of the contacts you searched for.
GET /api/contact_search/<Contact search report ID>
Description
This method fetches a contact search (without results) and it can also be used for checking the contact search status.
Response (Major fields)
Key | Description |
---|---|
status | Contact search status, 1 = Pending, 2 = Completed |
status_desc | Contact search status description (Pending / Completed) |
GET /api/contact_search/<Contact search report ID>/result
Description
This method fetches the contact search results. This is the same report you see in the UI under the Contact Manager Search and/or Analytics -> Contact Activity Report (if you provided include_behavior=true), when you click on the "View Report" icon. This API command provides the same results as the export below, only in this case, it returns the entire result as a JSON response instead of CSV file.
...
Code Block |
---|
{ "metadata": { "error": false, "fields": {}, "total": 3 }, "payload": [ { "email": "email1@gmail.com", "address": "", "country": "", "first_name": "", "last_name": "", "gender": "", "ip": "", "language": "", "phone": "", "os": "", "product_id": "0", "id": "55a4d31c2547e5f8537b23c6", "ocx_status": "Active", "ocx_created_date": "1436865308", "ocx_unsubscribe_date": "", "ocx_import_id": "" }, { "email": "email2@hotmail.com", "address": "", "country": "", "first_name": "", "last_name": "", "gender": "", "ip": "", "language": "", "phone": "", "os": "", "product_id": "0", "id": "55a4d3292547e52c7b7b23c7", "ocx_status": "Unsubscribed", "ocx_created_date": "1436865321", "ocx_unsubscribe_date": "1438503584", "ocx_import_id": "" }, { "email": "email3@yahoo.com", "address": "", "country": "", "first_name": "", "last_name": "", "gender": "", "ip": "", "language": "", "phone": "", "os": "", "product_id": "0", "id": "55b9ec3b2547e5720f7b23c6", "ocx_status": "Active", "ocx_created_date": "1438247995", "ocx_unsubscribe_date": "", "ocx_import_id": "" } ] } |
Error Codes
- 410 - Expired (when the requested report is expired)
GET /api/contact_search/<Contact search report ID>/export
Description
This method exports a contact search report already created.
GET /api/contact_search
Description
This method fetches a collection of contact searches (without the results).
...
Optional int
limit
Optional int
POST /api/contact_search
Description
This method creates a new contact search.
...
Code Block |
---|
{ "title": "All Members: Email is not empty", "include_behavior": false, "filters": { "type": "Active", "criteria": [{ "type": "string", "operator": "notempty", "operand": [""], "case_sensitive": 0, "condition": "and", "field_id": "123456" // This is the field id of the email field in that list. You can find that ID under List Settings -> Field Setup }], "user_type": "all" "from_date": 1467320400, "to_date": 1471381199 }, "combined_as_and": true } |
Response (Major fields)
Key | Description |
---|---|
id | Newly created contact search ID |
status | Contact search status, will always be 1 (Pending) in this response |
Response Example - For Creating a Contact Search for All Members in a Given List
Code Block |
---|
{ "metadata": { "error": false }, "payload": { "list_id": 12345, "title": "All Members: Email is not empty", "include_behavior": false, "filters": { "type": "Active", "criteria": [ { "type": "string", "operator": "notempty", "operand": [ "" ], "case_sensitive": 0, "condition": "and", "field_id": "123456", "field_name": "email" } ], "user_type": "all" }, "combined_as_and": true, "account_id": 1234, "status": 1, "desc": "Pending", "id": 82169, // This is ID of the search report that was created "created": 1470930202, "modified": 1470930202 } } |
DELETE /api/contact_search/<Contact search report ID>
Description
This method deletes a contact search.
...