Query the lists on your account

Method: GET

Endpoint: https://api.webexinteract.com/contacts/v1/lists

Parameters

Parameter name	Type	Mandatory	Example Values	Description
page_number	integer	No	1	Use in conjunction with page_size to return a subset. Defaults to 1 page if not given.
page_size	integer	No	1	Determines the number of items returned per page. Defaults to 10 items if not given.
sort_by	string	No	updated_at, created_at, name	Set the field that the items are sorted by. Defaults to updated_at if not given.
sort_order	string	No	DESC, ASC	Determines the order that the results are sorted by. Defaults to DESC if not given.
name	string	No	alistname	Search on lists existing on your account. Returns on a case insenstive, partial match basis. For example, a value of "alist" would return lists: alist alistname Alistname Calisto

Sample request

GET https://api.webexinteract.com/contacts/v1/lists/?sort_order=ASC&sort_by=name&page_size=30&page_number=1&name=alist

Sample response

{
  "paging": {
    "current_page": 1,
    "total_items": 3,
    "total_pages": 1
  },
  "items": [
    {
      "uid": "LST_99e604it00wHpm1LgPbBpJ4bITb",
      "name": "alist",
      "created_at": "2025-07-31T15:24:25Z",
      "updated_at": "2025-07-31T15:24:25Z"
    },
    {
      "uid": "LST_99e5yCpwsnl5p36C1y14AK5k3JY",
      "name": "alistname",
      "created_at": "2025-07-31T15:24:10Z",
      "updated_at": "2025-07-31T15:24:10Z"
    },
    {
      "uid": "LST_99duL5cOmHKBhLqwhI9KYkSrngI",
      "name": "Calisto",
      "created_at": "2025-07-31T13:48:31Z",
      "updated_at": "2025-07-31T13:51:26Z"
    }
  ]
}

{
  "trace_id": "dac476ae8714815f",
  "code": "ERR_CNT_VAL_001",
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 400,
  "timestamp": "2025-08-04T15:03:41.672018023Z",
  "validation_errors": [
    {
      "field": "filter.sortOrder",
      "message": "sorting.order.generic",
      "rejected_value": "ASCs"
    }
  ]
}

{
  "trace_id": "4caa751ed70540d4",
  "code": "ERR_CNT_VAL_001",
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 400,
  "timestamp": "2025-08-04T15:01:16.574302643Z",
  "validation_errors": [
    {
      "field": "filter.sortBy",
      "message": "sorting.by.generic",
      "rejected_value": "exampleitemdoesnotexist"
    }
  ]
}

{
  "trace_id": "f9d73f7eacdf93e4",
  "code": "ERR_CNT_VAL_004",
  "error": "INVALID_FORMAT",
  "message": "Invalid format for field 'page_size'. Expected format: int",
  "status": 400,
  "timestamp": "2025-08-04T15:04:59.809053718Z",
  "validation_errors": null
}

{
  "trace_id": "1c9d567be53781b5",
  "code": "ERR_CNT_VAL_004",
  "error": "INVALID_FORMAT",
  "message": "Invalid format for field 'page_number'. Expected format: int",
  "status": 400,
  "timestamp": "2025-08-04T15:08:04.733230910Z",
  "validation_errors": null
}

Create an empty list

Method: POST

Endpoint: https://api.webexinteract.com/contacts/v1/lists/create

Parameters

Parameter name	Type	Mandatory	Example values	Description
name	string	Yes	alistname	The name that will be set for the created list. 120 characters max.

Sample request

POST https://api.webexinteract.com/contacts/v1/lists/create

Sample response

{
  "uid": "LST_30pKUMCzHT0yoe9r5reNFqRqc6a",
  "name": "alistname"
}

{
  "trace_id": "c7ac82ee91e8152e",
  "code": "ERR_CNT_VAL_001",
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 400,
  "timestamp": "2025-08-04T15:11:58.515539363Z",
  "validation_errors": [
    {
      "field": "name",
      "message": "Invalid list name",
      "rejected_value": "doingalistoverapidoingalistoverapidoingalistoverapidoingalistoverapidoingalistoverapidoingalistoverapidoingalistoverapido"
    }
  ]
}

Delete a list

Method: DELETE

Endpoint: https://api.webexinteract.com/contacts/v1/lists/<uid>

Parameters

This endpoint requires no additional parameters.

Sample request

DELETE https://api.webexinteract.com/contacts/v1/lists/LST_30p2v1LIePstioxO365fKuj1KYZ

Sample responses

HTTP/1.1 204 No Content

{
  "trace_id": "7351705e38f343ce",
  "code": "ERR_CNT_VAL_001",
  "error": "INVALID_UID_FORMAT",
  "message": "Invalid UID format: 'LST_30p2v1LIePstioxO365fKuj1KYZa'. UIDs must follow the specified format.",
  "status": 400,
  "timestamp": "2025-08-04T15:14:37.040365244Z",
  "validation_errors": [
    {
      "field": "deleteList.uid",
      "message": "Invalid UID provided. LST_30p2v1LIePstioxO365fKuj1KYZa",
      "rejected_value": "LST_30pMv1LIePstioxO365fKuj1KYZa"
    }
  ]
}

Response Field Definitions

Field	Description
items/uid	UID for the list.
items/name	Name of the list.
items/created_at	The date time that the list was created.
items/updated_at	The date time that the list was last updated.