# Get DID Reservations

Returns a list of DID Reservations.

## Request

HTTP Method: `GET`

URI Path: `/v3/did_reservations`

Note

For all returned data attributes, see [Did Reservation Object](did-reservation-object.html).

### URI Query Parameters

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| include | `string` | No | [Inclusion](../../../specification/includes.html#api-includes) |
| filter[<filter\_name>] | `string` | No | [Filtering](../../../specification/filtering.html#api-filters) |
| fields[did\_reservations] | `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. The maximum is `100`. |

### Includes

| Value | Description |
| --- | --- |
| available\_did | [Available DID Object](../available-did/available-did-object.html#available-did-object-v35) |
| available\_did.did\_group | [DID Group Object](../did-group/did-group-object.html#did-group-object-v35) |
| available\_did.did\_group.stock\_keeping\_units | [Stock Keeping Unit Object](../../common-definitions/index.html#stock-keeping-unit-object-v35) |

### Filters

| Filter Name | Type | Allow Blank | Allow Array | Filters by: |
| --- | --- | --- | --- | --- |
| id | `string` | No | Yes | DID Reservation `id` field. |
| description | `string` | Yes | No | DID Reservations whose `description` field contains this value. |

### Sorting

| Value | Sorts by: |
| --- | --- |
| created\_at | The `created_at` field. |
| description | The `description` field. |
| expires\_at | The `expires_at` field. |

Prefix a value with `-` to sort in descending order.

## Examples

Simple RequestRequest with available\_did include

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/did_reservations HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET https://api.didww.com/v3/did_reservations -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": [
 6        {
 7            "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
 8            "type": "did_reservations",
 9            "attributes": {
10                "expires_at": "2022-06-27T10:52:16.564Z",
11                "created_at": "2022-06-27T10:42:16.577Z",
12                "description": "DIDWW"
13            },
14            "relationships": {
15                "available_did": {
16                    "links": {
17                        "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
18                        "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
19                    }
20                }
21            }
22        },
23        {
24            "id": "e85a5b1f-850d-498f-8418-ec74cccc9e9a",
25            "type": "did_reservations",
26            "attributes": {
27                "expires_at": "2022-06-27T10:59:58.131Z",
28                "created_at": "2022-06-27T10:49:58.151Z",
29                "description": "DIDWW"
30            },
31            "relationships": {
32                "available_did": {
33                    "links": {
34                        "self": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/relationships/available_did",
35                        "related": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/available_did"
36                    }
37                }
38            }
39        },
40        {
41            "id": "4789767d-d59a-485b-9adb-da14b4859f51",
42            "type": "did_reservations",
43            "attributes": {
44                "expires_at": "2022-06-27T11:00:03.332Z",
45                "created_at": "2022-06-27T10:50:03.344Z",
46                "description": "DIDWW"
47            },
48            "relationships": {
49                "available_did": {
50                    "links": {
51                        "self": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/relationships/available_did",
52                        "related": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/available_did"
53                    }
54                }
55            }
56        }
57    ],
58    "meta": {
59        "total_records": 3,
60        "available_count": 7,
61        "api_version": "2026-11-19"
62    },
63    "links": {
64        "first": "https://api.didww.com/v3/did_reservations?page%5Bnumber%5D=1&page%5Bsize%5D=50",
65        "last": "https://api.didww.com/v3/did_reservations?page%5Bnumber%5D=1&page%5Bsize%5D=50"
66    }
67}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/did_reservations?include=available_did HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api.didww.com/v3/did_reservations?include=available_did' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
  1HTTP/1.1 200 OK
  2Content-Type: application/vnd.api+json
  3
  4{
  5    "data": [
  6        {
  7            "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
  8            "type": "did_reservations",
  9            "attributes": {
 10                "expires_at": "2022-06-27T10:52:16.564Z",
 11                "created_at": "2022-06-27T10:42:16.577Z",
 12                "description": "DIDWW"
 13            },
 14            "relationships": {
 15                "available_did": {
 16                    "links": {
 17                        "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
 18                        "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
 19                    },
 20                    "data": {
 21                        "type": "available_dids",
 22                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573"
 23                    }
 24                }
 25            }
 26        },
 27        {
 28            "id": "e85a5b1f-850d-498f-8418-ec74cccc9e9a",
 29            "type": "did_reservations",
 30            "attributes": {
 31                "expires_at": "2022-06-27T10:59:58.131Z",
 32                "created_at": "2022-06-27T10:49:58.151Z",
 33                "description": "DIDWW"
 34            },
 35            "relationships": {
 36                "available_did": {
 37                    "links": {
 38                        "self": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/relationships/available_did",
 39                        "related": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/available_did"
 40                    },
 41                    "data": {
 42                        "type": "available_dids",
 43                        "id": "8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f"
 44                    }
 45                }
 46            }
 47        },
 48        {
 49            "id": "4789767d-d59a-485b-9adb-da14b4859f51",
 50            "type": "did_reservations",
 51            "attributes": {
 52                "expires_at": "2022-06-27T11:00:03.332Z",
 53                "created_at": "2022-06-27T10:50:03.344Z",
 54                "description": "DIDWW"
 55            },
 56            "relationships": {
 57                "available_did": {
 58                    "links": {
 59                        "self": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/relationships/available_did",
 60                        "related": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/available_did"
 61                    },
 62                    "data": {
 63                        "type": "available_dids",
 64                        "id": "7f396769-5203-470c-9595-b158c6bba7c8"
 65                    }
 66                }
 67            }
 68        }
 69    ],
 70    "included": [
 71        {
 72            "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
 73            "type": "available_dids",
 74            "attributes": {
 75                "number": "12124727602"
 76            },
 77            "relationships": {
 78                "did_group": {
 79                    "links": {
 80                        "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
 81                        "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
 82                    }
 83                },
 84                "nanpa_prefix": {
 85                    "links": {
 86                        "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
 87                        "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
 88                    }
 89                }
 90            }
 91        },
 92        {
 93            "id": "8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f",
 94            "type": "available_dids",
 95            "attributes": {
 96                "number": "526316907325"
 97            },
 98            "relationships": {
 99                "did_group": {
100                    "links": {
101                        "self": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/relationships/did_group",
102                        "related": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/did_group"
103                    }
104                },
105                "nanpa_prefix": {
106                    "links": {
107                        "self": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/relationships/nanpa_prefix",
108                        "related": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/nanpa_prefix"
109                    }
110                }
111            }
112        },
113        {
114            "id": "7f396769-5203-470c-9595-b158c6bba7c8",
115            "type": "available_dids",
116            "attributes": {
117                "number": "12124727603"
118            },
119            "relationships": {
120                "did_group": {
121                    "links": {
122                        "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/did_group",
123                        "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/did_group"
124                    }
125                },
126                "nanpa_prefix": {
127                    "links": {
128                        "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/nanpa_prefix",
129                        "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/nanpa_prefix"
130                    }
131                }
132            }
133        }
134    ],
135    "meta": {
136        "total_records": 3,
137        "available_count": 7,
138        "api_version": "2026-11-19"
139    },
140    "links": {
141        "first": "https://api.didww.com/v3/did_reservations?include=available_did&page%5Bnumber%5D=1&page%5Bsize%5D=50",
142        "last": "https://api.didww.com/v3/did_reservations?include=available_did&page%5Bnumber%5D=1&page%5Bsize%5D=50"
143    }
144}
```

[[DIDWW-API-EXAMPLE-END]]

## Top Level Meta Attributes

| Name | Type | Description |
| --- | --- | --- |
| available\_count | `integer` | Number of further DIDs the account can reserve under its numbers selection plan. |
| total\_records | `integer` | Total number of reservations that match the query. |
| api\_version | `string` | API version that served the request. |

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | [Bad Request](../../../specification/errors/index.html#api-bad-request) |
| 401 | No | [Unauthorized](../../authentication.html#authentication-v35) |
| 403 | No | Numbers selection is not enabled for the account. |
| 429 | No | The request budget of the account for the current window is spent (`too_many_requests`). `Retry-After` gives the number of seconds to wait. |
