Get the Deact Report

This operation retrieves a ZIP file of deactivated phone numbers.

Quick facts

Method

GET

Returns

CSV  file

Prerequisites

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

Definition

GET https://deact.openmarket.com/deact/v1/report?

Example request

Deactivated Numbers Report (Deact)

https://deact.openmarket.com/deact/v1/report?deactFileName=Acme-deacts&format=CSV&startDate=2014-04-20T00:00:00Z&endDate=2014-05-21T00:00:00Z&download=true

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.

Parameter

Description

s3Id

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

Required: no

deactFileName

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

Required: no

Multiple allowed

format

The file format, Must be CSV.

Required: no

Default: CSV

startDate

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

YYYY-MM-DDTHH:MM:SSZ

Required: no

endDate

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

YYYY-MM-DDTHH:MM:SSZ

Required: no

download

 

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

generatedStartDate

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

YYYY-MM-DDT00:00:00Z

Required: no

generatedEndDate

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

YYYY-MM-DDT00:00:00Z

Required: no

status

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

limit

Used in conjunction with offset.

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

Required: no

offset

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

sortBy

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

sortOrder

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.

Report

deactFileName

Deactivated Numbers Report (Deact)

<mobile-operator>-deacts

Header fields

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

For example:

GET /deact/v1/report HTTPS/1.1
Host: deact.openmarket.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Field

Description

Authorization

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">
     <format>CSV</format>
     <categories>
        <category>DEACT</category>
     </categories>
  </report>
</reports>

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.

Troubleshooting

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"/>