# 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](did-history-object.html).

### URI Query Parameters

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| filter[<filter\_name>] | `string` | No | [Filtering](../../../specification/filtering.html#api-filters) |
| fields[did\_history] | `string` | No | [Sparse fieldsets](../../../specification/sparse-fieldsets.html#api-sparse-fieldsets) |
| sort | `string` | No | [Sorting](../../../specification/sorting.html#api-sorting) |
| page[number] | `integer` | No | [Page number](../../../specification/pagination.html#api-pagination). |
| page[size] | `integer` | No | [Page size](../../../specification/pagination.html#api-pagination). 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

[[DIDWW-API-EXAMPLE-START]]

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"
    }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
GET /v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z 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?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z' -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": "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?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z&page%5Bnumber%5D=1&page%5Bsize%5D=50",
        "last": "https://api.didww.com/v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z&page%5Bnumber%5D=1&page%5Bsize%5D=50"
    },
    "meta": {
        "total_records": 2,
        "api_version": "2026-04-16"
    }
}
```

[[DIDWW-API-EXAMPLE-END]]

## 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](../../../configuration.html#api-key) |

On this page