# Add the custom domain

> Adds the hostname as pending and checks it once. Publish the records in the answer, then verify. Needs a `domain:write` token and `custom_domain` on the plan.

```json
{
  "/api/v1/domain": {
    "post": {
      "operationId": "createDomain",
      "tags": [
        "Domain"
      ],
      "summary": "Add the custom domain",
      "description": "Adds the hostname as pending and checks it once. Publish the records in the answer, then verify. Needs a `domain:write` token and `custom_domain` on the plan.",
      "security": [
        {
          "bearerAuth": []
        }
      ],
      "requestBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DomainCreate"
            }
          }
        }
      },
      "responses": {
        "201": {
          "description": "Added.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Domain"
              }
            }
          }
        },
        "400": {
          "description": "The hostname is not valid, is reserved or was refused by the host (`errors` names the reason).",
          "content": {
            "application/problem+json": {
              "schema": {
                "$ref": "#/components/schemas/Problem"
              }
            }
          }
        },
        "401": {
          "description": "Missing, unknown, revoked or expired token.",
          "content": {
            "application/problem+json": {
              "schema": {
                "$ref": "#/components/schemas/Problem"
              }
            }
          }
        },
        "403": {
          "description": "The token's scope does not allow this request.",
          "content": {
            "application/problem+json": {
              "schema": {
                "$ref": "#/components/schemas/Problem"
              }
            }
          }
        },
        "409": {
          "description": "The school has a domain, the hostname is taken, the plan lacks `custom_domain` (`notEntitled`) or domains are not available on this deployment (`unavailable`).",
          "content": {
            "application/problem+json": {
              "schema": {
                "$ref": "#/components/schemas/Problem"
              }
            }
          }
        }
      }
    }
  }
}
```