Message Search API

Important Updates

The Message Search API now includes a urlMetadata field, enabling you to identify URLs originated from a QR code. During a 90-day transition period (till November 22, 2025), both the existing urls field and the new urlMetadata field will be supported. After this period, only urlMetadata will be available, providing better visibility of QR code URLs in messages.

Message Search API retrieves the message information from ETD using the JWT created by the Authentication API.

Available Message Search API endpoints are:

Americas API endpoint: 

https://api.us.etd.cisco.com/v1/messages/search

Europe API endpoint: 

https://api.de.etd.cisco.com/v1/messages/search

Australia API endpoint:

https://api.au.etd.cisco.com/v1/messages/search

India API endpoint:

https://api.in.etd.cisco.com/v1/messages/search

UAE API endpoint:

https://api.ae.etd.cisco.com/v1/messages/search

Example of a Message Search API request using CURL:

  curl -X POST \ 

https:// api.us.etd.cisco.com/v1/messages/search -H 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjEDFHSHgxMzEsImlhdCI6MTY4MTkxNDUzMSwic3ViIjoi YXBpLWSTYWKLdCIsImF1ZCI6InB1YmxpYy1hcGDFGFDGllbnRJZCI6ImVjNzQxZGZhLWUzMzk 
tNGY1NS1hMGZmLTSDFGSFM2IwN2NlMSIsInRlbmFudElkIjoiY2M4YjkwZjQtMSDHSFH0xMWVhLWFmMDgtOGMxNjQ1NGZGFHJ6FJD4 
.ZMMoPWCr3xq2dd9CRbbcHI836Nk4B1o0d5pIfY_JZ2c' \ 
  -H 'x-api-key: apikeyTest’ \

  -H 'cache-control: no-cache' \ 

  -H 'content-type: application/json' \ 

  -d '{"timestamp":["2023-12-01T09:34:05.361Z","2023-12-19T17:34:05.361Z"]}'

Note:

  1. The Timestamp field is mandatory in the request body. It is an ISO 8601 formatted date-time string range, for example, ["2023-02-01T12:00:00Z", "2023-02-20T23:59:59Z"]. The start and end dates are inclusive. Timestamps should be in the UTC timezone only. The first timestamp should be earlier than the second.
  2. The Message search API allows searches for a period of 32 days. The date range should not exceed 90 days in the past.
  3. The current page limit is 100 messages per request. You can use the nextPage token to navigate if you get more than 100 results on your query.

Responses

Using the API may produce different responses for the HTTP request. Here are the expected results:

Code Message Description
200 Success The request was process and executed.
400 Bad Request The request is misformatted or there is not enough information to authenticate the request.
401 Unauthorized Authorization information is either missing, incomplete, or incorrect.
404 Not Found The requested resource does not exist.
500 Internal Server Error The request was not processed successfully, or no better response to the request is available.
502 Bad Gateway The server generated a response that exceeds the limit. Reduce the page size or time range.