# Declare your portal domain.

> Serve your sellers' portal on a subdomain of a domain you own. Create the two records the answer lists: a `CNAME` from the domain to `portals.wajub.app`, and a `TXT` record at `_wajub-verify.<domain>` carrying the token. Wajub checks them every ten minutes for `verify_hours` (72), then routes the domain and gets its TLS certificate: the status turns `active` and every portal link you get from the API (`portal_session.url`, `loader_url`) uses it. Your sellers' e-mails name it too.

`PUT https://api.wajub.com/sync/portal_domain`

Serve your sellers' portal on a subdomain of a domain you own. Create the two records the answer lists: a `CNAME` from the domain to `portals.wajub.app`, and a `TXT` record at `_wajub-verify.<domain>` carrying the token. Wajub checks them every ten minutes for `verify_hours` (72), then routes the domain and gets its TLS certificate: the status turns `active` and every portal link you get from the API (`portal_session.url`, `loader_url`) uses it. Your sellers' e-mails name it too.

One domain per platform. Declaring the domain you already declared changes nothing (`200`); declaring another replaces one still being verified; an `active` one has to be removed first (`409 portal_domain_active`). Declaring again a domain that failed or was removed keeps its token. A domain Wajub blocked cannot be declared by any platform (`409 domain_blocked`): Wajub can block one in use, removed, failed or never declared. Once active, the records are checked again every day: three failures in a row, or no answer from your zone for more than 72 hours in a row, turn it `failed` and every link goes back to your `{name}.wajub.app` address.

A live key only (`403 live_key_required`): the domain serves your live sellers. A test key can read it.

## Body (application/json)

- `domain` (string, required): A subdomain of a domain you own: no scheme, no path, no wildcard, not a zone's root. `https://` and a trailing slash are dropped; stored in lower case.

## Responses

- `200`: Already declared: nothing changes
- `201`: Created
- `403`: Forbidden
- `409`: Conflict
- `422`: Unprocessable Content

## Example response (200)

```json
{
  "portal_domain": {
    "domain": "vendeurs.maplateforme.com",
    "status": "pending_dns",
    "records": [
      {
        "type": "CNAME",
        "name": "vendeurs.maplateforme.com",
        "value": "portals.wajub.app"
      },
      {
        "type": "TXT",
        "name": "_wajub-verify.vendeurs.maplateforme.com",
        "value": "wajub-portal-3f9c…"
      }
    ],
    "last_error": "txt_missing",
    "checks": 4,
    "last_checked_at": "2026-11-20T10:40:00+00:00",
    "verify_deadline_at": "2026-11-23T10:00:00+00:00",
    "verify_hours": 72,
    "activated_at": null,
    "failed_at": null,
    "removed_at": null,
    "removal_reason": null
  }
}
```
