Get the Deact Report

This operation retrieves a ZIP file of deactivated phone numbers.

Quick facts




CSV  file


Your account must be provisioned to allow deact report access.

Note: When you request deact reports, the file returned is zipped.

Using this operation

This operation supports a variety of parameters that let you retrieve the specific report you want. To determine which parameters to use in your request, we recommend you first retrieve a list of the reports you have permission to access. This will return metadata about the reports that will help you construct a proper request.

This endpoint is also used for the Get List of Available Reports operation. To download a report, include the Deact File Name and set download to true. You can download only one report per request. Therefore, ensure that your request only identifies one unique report. If you don't include the download parameter, then you will retrieve a list of reports.

For a list of the Deact File Names for deactivation reports, see Handling Deactivated Phone Numbers.

Making a Request



Example request

Deactivated Numbers Report (Deact)

Query parameters

There are a variety of URL parameters to make your query more specific. For example, you can request a particular report and a specific format, time period, and short code. Assuming your request uses parameters that match the deactFileName you have specified, the API will return the report in the format you requested.

You can include some parameters multiple times in a request. These are indicated in the table below with Multiple allowed. You can include other parameters just once.




Unique resource ID for a specific report. This is a hexadecimal string.

Required: no


File name of the report to download. See Deact File Name below.

Required: no

Multiple allowed


The file format, Must be CSV.

Required: no

Default: CSV


The date/time when the report period begins (in UTC). The format is:


Required: no


The date/time when the report period ends (in UTC). The format is:


Required: no



A Boolean value that determines whether you want a list of reports, or to download a report.

  • false — Returns a list of reports (that best match the parameters supplied, and the user's permission).
  • true — Downloads a specified report.

Required: no

Default: false


Start date in UTC when the report was generated. The format is:


Required: no


End date in UTC when the report was generated. The format is:


Required: no


Report status must be "processed"

Defaults to "processed" if download parameter is set to True and no status is explicitly given.

Required: no

Default: processed


Used in conjunction with offset.

Maximum number of results to return in the response. Used for pagination. This is an integer.

Required: no


Used in conjunction with limit.

What number in the result set to start with in the response. Used for pagination. This is an integer.

Required: no


Used in conjunction with sortOrder.

Results are returned using the sortBy and sortOrder fields. Must be one of:

  • startDate
  • endDate
  • generatedStartDate
  • generatedEndDate
  • name

Required: no


Used in conjunction with sortBy.

Results are returned using the sort by and sort order fields. Either:

  • asc — ascending order; A to Z, 1 to 9.
  • desc — descending order; 9 to 1, Z to A.

Required: no

Deact File Name

The deactFileName specifies the deact report you want. The following table lists the deactFileNames you can use.



Deactivated Numbers Report (Deact)


Header fields

You must provide your authentication details using Basic authentication in the header.

For example:

GET /deact/v1/report HTTPS/1.1
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=




Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticate with OpenMarket.

Required: Always

Important: This API only accepts HTTPS with TLS 1.2 or higher.

Response from OpenMarket

Accepted requests

If your request is accepted then OpenMarket returns the specified CSV or XML file. To find out about the fields in the different reports, see:

Response message

The following shows an example query response message where a total of 826 records are returned where the limit is set to 1:

<reports total="826" limit="1">
  <report detailLevel="ITEMIZED" status="PROCESSED" dataSource="deact" deactFileName="blue-deacts" size="207" generatedDate="2019-03-20T14:30:36Z" deletionDate="2019-05-19T00:00:00Z" startDate="2019-03-20T00:00:00Z" endDate="2019-03-21T00:00:00Z" s3Id="49225332-0049-4b8c-af58-899f6e54e27c">

In all responses deletionDate is used to indicate the date on which the file will be deleted per data retention policy. The file in this example will be deleted on May 19, 2019.


I couldn't download a report

The download parameter must be set to true to download a report. If it cannot find a report at all, you'll receive the response:

<reports total="0"/>