---
title: "Add a domain"
method: POST
path: "/customers/{id}/domains"
tags: ["Partners"]
---

# Add a domain

`POST /customers/{id}/domains`

## Request

- Base URL: `https://faivelo.com/api/partner`
- URL: `https://faivelo.com/api/partner/customers/{id}/domains`
- Auth: HTTP bearer

Add a domain to a customer on a plan; the domain is billed from the next sync. The response lists the DNS records to show them; there is no registrar auto-injection on this path. Poll the domain with `verify=true` until `verified` is true. Refused with **403** `PARTNER_DOMAIN_LIMIT` at your domain limit, which grows with clean sending. Requires `partner:write`.

## Path parameters

- `id` string, required

## Request body

- object
  - `domain` string, required
  - `brandName` string, nullable: Shown in the customer's webmail instead of the bare domain
  - `plan` 'STARTER' | 'GROWTH' | 'PRO' | 'BUSINESS': The plan this domain is billed at; it sets the storage shared by its mailboxes. Default: the customer's current plan

## Response `201`

The domain with the records to publish

- object
  - `success` boolean
  - `data` PartnerDomain
    - `domain` string
    - `verified` boolean
    - `brandName` string, nullable
    - `mailboxes` integer
    - `createdAt` string, date-time
    - `dnsRecords` PartnerDnsRecord[]: Show these to the customer; poll with `verify=true` until every record is verified
      - `type` string
      - `name` string
      - `value` string
      - `verified` boolean
      - `lastCheck` string, date-time, nullable
    - `storage` StorageSummary, nullable: Bytes used and allowed. Null when the mail server could not answer.
      - `usedBytes` integer
      - `limitBytes` integer, nullable
      - `availableBytes` integer, nullable
    - `storageLimitBytes` integer, nullable: The cap you set, or null when only the plan storage applies
    - `plan` 'STARTER' | 'GROWTH' | 'PRO' | 'BUSINESS': The plan this domain is billed at; it sets the storage shared by its mailboxes, contacts and Drive

## Other responses

- `400`: Invalid input
- `401`: Missing or invalid API key, or not a partner key
- `403`: The key lacks the required scope, or provisioning is refused (partner paused, customer cap reached)
- `404`: Not found, including any customer that is not yours
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/faivelo/apis/faivelo-api.md) · [All operations](https://skmtc.dev/faivelo/apis/faivelo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faivelo/apis/faivelo-api/revisions/a7413ddea5d1?raw)