Get DID Histories

Returns a list of DID history records for your account. Only records from the last 90 days are available. The data is sourced from events shown on the billing Histories page, and older records in that 90-day window are backfilled with UUID values.

Request

HTTP Method: GET

URI Path: /v3/did_history

Note

For all returned data attributes, see Did History Object.

URI Query Parameters

Name	Type	Is Required?	Description
filter[<filter_name>]	string	No	Filtering
fields[did_history]	string	No	Sparse fieldsets
sort	string	No	Sorting
page[number]	integer	No	Page number.
page[size]	integer	No	Page size. Pagination defaults to 50 records per page.

Filters

Filter Name	Type	Allow Blank	Allow Array	Filters by:
id	string	No	Yes	The DID history UUID.
did_number	string	No	No	The DID number.
action	string	No	No	The action value.
method	string	No	No	The method value.
created_at_gteq	string	No	No	Records created on or after the specified date and time.
created_at_lteq	string	No	No	Records created on or before the specified date and time.

Available Action Values

Value	Description
assigned	DID assignment event.
renewed	DID renewal event.
canceled	DID cancellation event.
removed	DID release or removal event.
billing_cycles_count_changed	Billing cycles count change event.
restored	DID restoration event.

Note

The meta.from and meta.to values are returned only for billing_cycles_count_changed records.

Available Method Values

Value	Description
system	Action performed by the system.
api2	Action performed through API v2.
api3	Action performed through API v3.
staff	Action performed by staff.
user_panel	Action performed from the user panel.

Sorting

Value	Sorts by:
created_at	Creation timestamp

Examples

Simple RequestFilter by Timeframe

http

GET /v3/did_history HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

curl

curl -i -X GET https://api.didww.com/v3/did_history -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json"

response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "data": [
        {
            "id": "9e3b65e9-fdc4-1810-9e93-b7127ab6b976",
            "type": "did_history",
            "attributes": {
                "did_number": "437xxxxxxxxx",
                "action": "removed",
                "method": "api3",
                "created_at": "2026-03-06T15:11:00.326Z"
            }
        },
        {
            "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "type": "did_history",
            "attributes": {
                "did_number": "437xxxxxxxxx",
                "action": "renewed",
                "method": "api2",
                "created_at": "2026-04-16T11:30:00.000Z"
            }
        },
        {
            "id": "9e3b65e9-fdc4-1810-9e93-b7127ab59ee6",
            "type": "did_history",
            "attributes": {
                "did_number": "437xxxxxxxxx",
                "action": "billing_cycles_count_changed",
                "method": "staff",
                "created_at": "2026-04-03T17:42:45.728Z"
            },
            "meta": {
                "from": "empty",
                "to": "5"
            }
        }
    ],
    "links": {
        "first": "https://api.didww.com/v3/did_history?page%5Bnumber%5D=1&page%5Bsize%5D=50",
        "last": "https://api.didww.com/v3/did_history?page%5Bnumber%5D=1&page%5Bsize%5D=50"
    },
    "meta": {
        "total_records": 3,
        "api_version": "2026-04-16"
    }
}

Other Responses

Code	Success	Description
400	No	Invalid filter value, invalid sort criteria, or the created_at filter date is outside the last 90 days.
401	No	Unauthorized