Create and manage contacts within your lists.
Query the contacts within a list
Method: GET
Parameters
| Parameter name | Type | Mandatory | Example Values | Description |
|---|---|---|---|---|
| search | integer | No | +44781234000 | Exact match phone number/whatsapp phone number search. |
| page_number | integer | No | 1 | Determines which page is returned. Use in conjunction with page_size to control the set of contacts you want to get. All pages are returned if not given. |
| page_size | integer | No | 10 | Determines how many items will be returned per page. Min: 1 Max: 100 |
| fields | string | No | phone_number, title, firstname | Set the contact fields to be returned for each contact. If not set, all contact fields are returned. |
Sample request
GET https://api.webexinteract.com/contacts/v1/contacts/list/LST_099uL5cOmHKBhLqwhI9KYkSrngI?page_number=1&page_size=2
Sample response
{
"paging": {
"current_page": 1,
"total_items": 2,
"total_pages": 1
},
"items": [
{
"zip": "AB11 6AA",
"country": "GB",
"firstname": "Matt",
"whatsapp_id": "+447878805000",
"field_3": null,
"city": "Port Hiram",
"date_of_birth": "Sun May 27 07:23:57 BST 1979",
"address_1": "456 Aroad",
"field_1": null,
"address_2": "Aplace",
"field_2": null,
"created_at": "2025-08-06 13:13:16",
"phone_region": "GB",
"title": "Dr",
"lastname": "Jones",
"uid": "CON_30umnHdxDUKZ0VJSPeefhXWzdYr",
"email_address": "[email protected]",
"updated_at": null,
"company_name": "MJ CO",
"whatsapp_region": "GB",
"phone_number": "+447879040000",
"alternate_phone": null,
"state": "Shropshire"
},
{
"zip": "WR1 1AA",
"country": "GB",
"firstname": "Rupert",
"whatsapp_id": "+447878802000",
"field_3": null,
"city": "Worcester",
"date_of_birth": "Fri Jul 23 14:05:57 BST 1965",
"address_1": "123 Example Road",
"field_1": null,
"address_2": "Someplace",
"field_2": null,
"created_at": "2025-08-06 13:13:16",
"phone_region": "GB",
"title": "Mrs",
"lastname": "Neve",
"uid": "CON_30umnChxDkTubfkSoDo31YwyGOI",
"email_address": "[email protected]",
"updated_at": null,
"company_name": "RobelBorert",
"whatsapp_region": "GB",
"phone_number": "+447807121000",
"alternate_phone": null,
"state": "Worcestershire"
}
]
}
{
"trace_id": "57bd01a3ef6be70e",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T13:17:49.076588217Z",
"validation_errors": [
{
"field": "search.pageSize",
"message": "page.size.generic",
"rejected_value": 0
}
]
}
{
"trace_id": "264a088488950a54",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T13:21:38.151611848Z",
"validation_errors": [
{
"field": "search.fields[3].<list element>",
"message": "Contact retrieval field is invalid.",
"rejected_value": "a"
}
]
}
{
"trace_id": "9a5d8f5b6023d041",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Contact fields are missing from the request.",
"status": 400,
"timestamp": "2025-08-06T13:24:15.982073398Z",
"validation_errors": null
}
Create and update contacts
Method: POST
Asynchronous Processing
A successful request adds the contact creation job to a queue. To be notified of when the job has been completed, add a callback URL to the request.
Parameters
| Parameter name | Type | Mandatory | Example values | Description |
|---|---|---|---|---|
| list_id | string | Yes | LST_90duL5cOmHKPhLqwhI9KYkSrnzI | Provide the ID of the list that the contacts are to be added to. |
| phone_region | string | No | See <WIP - refer to a dedicated doc for supported country codes> | <clarify with dev - assume to allow local formats for specified country> Defaults to GB if not given. |
| merge_type | string | Yes | skipDuplicates allowDuplicates mergeByPhoneNumberInList mergeByWhatsappIdInList | skipDuplicates - Skip contact creation if a contact already exists in the list with the same phone_number. allowDuplicates - Create a new contact even if a contact already exists in the list with the same phone_number. mergeByPhoneNumberInList - Update attributes and custom fields for instances of contacts having the same phone number. mergeByWhatsappIdInList - Update attributes and custom fields for instances of contacts having the same whatsapp_number. |
| callback_url | string | No | https://exwhreceiver.com/contcomp | Provide a URL to receive a webhook to notify when the contact creation process has completed. See for contact callback webhook details. |
| correlation_id | string | No | anexternalidexample123 | Provide a correlation ID which will be returned on the contact callback webhook. |
| contacts | object | Yes | N/A | |
| phone_number | string | Yes if whatsapp_number not provided | +44781234000 | Maps to the associated contact attribute. Max: 16 characters |
| whatsapp_number | string | Yes if phone_number not provided | +44781234000 | Maps to the associated contact attribute. Max: 16 characters |
| title | string | No | Dr | Maps to the associated contact attribute. Max:30 characters |
| firstname | string | No | Peter | Maps to the associated contact attribute. Max: 50 characters |
| lastname | string | No | Venkman | Maps to the associated contact attribute. Max: 50 characters |
| date_of_birth | string | No | 18th July 1946 | Maps to the associated contact attribute. Max: 255 characters |
| address_1 | string | No | 644 Broadway | Maps to the associated contact attribute. Max: 255 characters |
| address_2 | string | No | Broadway | Maps to the associated contact attribute. Max: 255 characters |
| city | string | No | New York | Maps to the associated contact attribute. Max: 128 characters |
| zip | string | No | NY 10012 | Maps to the associated contact attribute. Max: 24 characters |
| state | string | No | New York | Maps to the associated contact attribute. Max: 48 characters |
| country | string | No | US | Maps to the associated contact attribute. Max: ? |
| company_name | string | No | Ghostbusters | Maps to the associated contact attribute. Max: 128 characters |
| email_address | string | No | [email protected] | Maps to the associated contact attribute. Max: 255 characters |
| alternate_phone | string | No | +44781234000 | Maps to the associated contact attribute. Max: 128 characters |
field_<#> | string | No | anexamplecustom value. | Maps to the associated custom field. For each custom field which has been created in the Webex Interact app, an incrementing numeric ID is given. Max: ? |
Sample request
{
"contacts": [
{
"phone_number": "+447807121000",
"whatsapp_number": "+447878802000",
"title": "Mr",
"company_name": "RND",
"date_of_birth": "July 31, 1926",
"city": "Newton Abbot",
"state": "Devon",
"zip": "TQ12 1AA",
"country": "GB",
"alternate_phone": "+447807123000",
"email_address": "[email protected]",
"firstname": "Rupert",
"lastname": "Neve",
"address_1": "123 Example Road",
"address_2": "Newton Abbot"
},
{
"phone_number": "+447879040000",
"whatsapp_number": "+447878805000",
"title": "Dr",
"company_name": "MJ CO",
"date_of_birth": "Sun May 27 07:23:57 BST 1979",
"city": "Port Hiram",
"state": "Shropshire",
"zip": "AB11 6AA",
"country": "GB",
"alternate_phone": "+447874276000",
"email_address": "[email protected]",
"firstname": "Matt",
"lastname": "Jones",
"address_1": "456 Aroad",
"address_2": "Aplace"
}
],
"list_id": "LST_90duL5cOmHKZhLqwhI9KYkSrnzI",
"phone_region": "GB",
"merge_type": "mergeByPhoneNumberInList",
"callback_url": "https://somereceiver.site/0a316f99-a699-4a7f-a333-8b7f55499999",
"correlation_id": "example correlation id"
}
Sample response
{
"list_id": "LST_30duL5cOmHKBhLqwhI9KYkSrngI",
"list_name": "a list for deletion",
"message": "Contact request has been queued successfully",
"code": "SUCCESS_CNT_GEN_001"
}
{
"trace_id": "ca20fed9fb6ed529",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T15:33:19.398194146Z",
"validation_errors": [
{
"field": "createContacts.request.conCreateRequests[0]",
"message": "message = Invalid request: either 'phone_number' or 'whatsapp_number' must be provided for a contact.",
"rejected_value": {
"title": "Mrs",
"company_name": "RobelBorert",
"date_of_birth": "Fri Jul 23 14:05:57 BST 1965",
"city": "Worcester",
"state": "Worcestershire",
"zip": "WR1 1AA",
"country": "GB",
"alternate_phone": "+447807123000",
"email_address": "[email protected]",
"firstname": "Rupert",
"lastname": "Neve",
"address_1": "123 Example Road",
"address_2": "Someplace"
}
}
]
}
{
"trace_id": "0433562ca75f1ede",
"code": "ERR_CNT_VAL_001",
"error": "BAD_REQUEST",
"message": "List not found",
"status": 400,
"timestamp": "2025-08-06T15:36:09.970766521Z",
"validation_errors": null
}
{
"trace_id": "0e696d657487d3a2",
"code": "ERR_CNT_VAL_001",
"error": "INVALID_UID_FORMAT",
"message": "Invalid UID format: 'LST_30duL5cOmHKBhLqwhI9KYkSrngIa'. UIDs must follow the specified format.",
"status": 400,
"timestamp": "2025-08-06T15:37:34.496861680Z",
"validation_errors": [
{
"field": "createContacts.request.listUid",
"message": "Invalid UID provided. LST_30duL5cOmHKBhLqwhI9KYkSrngIa",
"rejected_value": "LST_30duL5cOmHKBhLqwhI9KYkSrngIa"
}
]
}
{
"trace_id": "13ad4810c3cd4e8f",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T15:38:03.752336373Z",
"validation_errors": [
{
"field": "createContacts.request.phoneRegion",
"message": "Invalid phone number region code.",
"rejected_value": "GBa"
}
]
}
{
"trace_id": "9591951b5c355631",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T15:39:15.056218665Z",
"validation_errors": [
{
"field": "createContacts.request.mergeType",
"message": "Invalid merge_type. Allowed values: skipDuplicates, allowDuplicates, mergeByPhoneNumberInList, mergeByWhatsappIdInList.",
"rejected_value": "mergeByPhoneNumberInLista"
}
]
}
{
"trace_id": "4b8149cd8a296576",
"code": "ERR_CNT_REQ_002",
"error": "INVALID_REQUEST_BODY",
"message": "Invalid or malformed request body. Please check your JSON format and ensure all required fields are provided.",
"status": 400,
"timestamp": "2025-08-06T15:40:29.029039615Z",
"validation_errors": null
}
{
"trace_id": "43ff31f358c7cc65",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T15:41:33.860823670Z",
"validation_errors": [
{
"field": "createContacts.request.conCreateRequests[0]",
"message": "Invalid phone number.",
"rejected_value": {
"phone_number": "+447807121000a",
"title": "Mrs",
"company_name": "RobelBorert",
"date_of_birth": "Fri Jul 23 14:05:57 BST 1965",
"city": "Worcester",
"state": "Worcestershire",
"zip": "WR1 1AA",
"country": "GB",
"alternate_phone": "+447807123000",
"whatsapp_number": "+447878802000",
"email_address": "[email protected]",
"firstname": "Rupert",
"lastname": "Neve",
"address_1": "123 Example Road",
"address_2": "Someplace"
}
}
]
}
{
"trace_id": "ba09b49618a7a25c",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T15:43:23.705639446Z",
"validation_errors": [
{
"field": "createContacts.request.conCreateRequests[0].zip",
"message": "size must be between 1 and 24",
"rejected_value": "WR1 1AAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}
{
"trace_id": "3f4f72c9a38750cf",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T15:44:47.108193258Z",
"validation_errors": [
{
"field": "createContacts.request.conCreateRequests[0].title",
"message": "size must be between 1 and 30",
"rejected_value": ""
}
]
}
{
"trace_id": "5679b6995d603a30",
"code": "ERR_CNT_VAL_001",
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 400,
"timestamp": "2025-08-06T15:46:33.448292308Z",
"validation_errors": [
{
"field": "createContacts.request.conCreateRequests",
"message": "must not be empty",
"rejected_value": []
}
]
}
Delete a contact
Method: DELETE
Use
Delete a contact in a list.
Parameters
This endpoint requires no additional parameters.
Sample request
DELETE https://api.webexinteract.com/contacts/v1/contacts/CON_30pZyYWExr9hWIMvVljqo0AkL1O
Sample responses
HTTP/1.1 204 No Content