# Add Custom Domain

Adds a Custom Domain to the instance. The Custom Domain must be unique across all instances. Once the domain is added, it will be used to route requests to this instance. This method requires system level permissions and cannot be called from an instance context.

## Required permissions:

- `system.domain.write`

## POST

``
/zitadel.instance.v2.InstanceService/AddCustomDomain
``

### Send

#### Header

### [Header Parameters](/content/docs/reference/api/instance/zitadel.instance.v2.InstanceService.AddCustomDomain#parameters-header/index.html)

- **Connect-Protocol-Version***: Define the version of the Connect protocol
  - Value in `1`

- **Connect-Timeout-Ms?**: Define the timeout, in ms

### [Request Body](/content/docs/reference/api/instance/zitadel.instance.v2.InstanceService.AddCustomDomain#request-body/index.html)

Format: `application/json`

#### TypeScript Definitions

Use the request body type in TypeScript.

```json
{
  "instanceId": "string",
  "customDomain": "string"
}
```

### [Response Body](/content/docs/reference/api/instance/zitadel.instance.v2.InstanceService.AddCustomDomain#response-body/index.html)

#### 200  `application/json`

```json
{
  "creationDate": "2023-01-15T01:30:15.01Z"
}
```

#### default  `application/json`

```json
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}
```

## cURL Example

```bash
curl -X POST "https://example.com/zitadel.instance.v2.InstanceService/AddCustomDomain" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "string",
    "customDomain": "string"
  }'
```