# Create DID Reservation

Creates a DID Reservation.

## Request

HTTP Method: `POST`

URI Path: `/v3/did_reservations`

### Request Body Object Attributes

| Name | Type | Nullable | Is Required? | Description |
| --- | --- | --- | --- | --- |
| description | `string` | Yes | No | Free-form customer note. |

### Request Body Object Relationships

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| available\_did | [To one](../../../specification/relationships.html#api-relationships) | Yes | The Available DID to reserve. |

## Example

[[DIDWW-API-EXAMPLE-START]]

http

```
 1POST /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]
 6
 7{
 8  "data": {
 9    "type": "did_reservations",
10    "attributes": {
11      "description": "DIDWW"
12    },
13    "relationships": {
14      "available_did": {
15        "data": {
16          "type": "available_dids",
17          "id": "8bc37f63-acd7-4e43-a760-1a1caa6e4683"
18        }
19      }
20    }
21  }
22}
```

curl

```
1curl -i -X POST 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]" --data-raw '{"data": {"attributes": {"description": "DIDWW"}, "relationships": {"available_did": {"data": {"id": "8bc37f63-acd7-4e43-a760-1a1caa6e4683", "type": "available_dids"}}}, "type": "did_reservations"}}'
```

response

```
 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": {
 6    "id": "80167e78-62a1-4720-bf00-229fa7e1935d",
 7    "type": "did_reservations",
 8    "attributes": {
 9      "expires_at": "2018-03-15T12:34:56.000Z",
10      "created_at": "2018-03-15T12:14:56.000Z",
11      "description": "DIDWW"
12    },
13    "relationships": {
14      "available_did": {
15        "links": {
16          "self": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d/relationships/available_did",
17          "related": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d/available_did"
18        }
19      }
20    }
21  },
22  "meta": {
23    "api_version": "2026-11-19"
24  }
25}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 201 | Yes | Created DID Reservation with not reserved Available DID.Returns [DID Reservation Object](did-reservation-object.html#did-reservation-object-v35) |
| 422 | No | [Unprocessable Entity](../../../specification/errors/index.html#api-validation-error-object) |
| 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. Also returned when the access token carries the `read` scope, which does not cover this method (title `Insufficient scope`, `WWW-Authenticate: Bearer error="insufficient_scope"`). See [Scopes](../../authentication.html#authentication-scopes-v35). |
| 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. |
