Register a subdomain

Register a new custom subdomain and receive its DNS records. Optionally pass webhook_url to get a signed POST callback on every status change instead of polling; the signing secret is returned once in this response as webhook_secret.

POST /subdomains

Create subdomain

cURL

curl --request POST \
  --url https://management-api.fpjs.io/subdomains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: <x-api-version>' \
  --data '
{
  "subdomain": "metrics.yourwebsite.com",
  "webhook_url": "https://customer.com/hooks/fp-subdomain"
}
'

201

{
  "data": {
    "id": "certv2_a1b2c3d4e5f6",
    "subdomain": "metrics.yourwebsite.com",
    "status": "pending",
    "created_at": "2026-03-05T14:00:00.000Z",
    "updated_at": "2026-03-05T14:35:00.000Z",
    "dns_records": {
      "verification": {
        "type": "CNAME",
        "host": "_acme-challenge.metrics.yourwebsite.com",
        "value": "dcv.fpjs.io",
        "status": "pending_validation"
      },
      "routing": [
        {
          "type": "CNAME",
          "host": "_acme-challenge.metrics.yourwebsite.com",
          "value": "dcv.fpjs.io",
          "status": "pending_validation"
        }
      ]
    },
    "webhook_url": "https://customer.com/hooks/fp-subdomain",
    "webhook_secret": "whsec_wRNftLajMZNeslQOP6vEPm4iVx5NlZ6z"
  }
}

Every DNS record you need is returned in this response at once: the verification CNAME record and the two routing A records. You can add them all to your DNS provider in a single pass. The A records start routing traffic only after your certificate is issued, so adding them early is safe.

Optionally pass a webhook_url to receive a signed POST callback each time the subdomain’s status changes, instead of polling Get subdomain. The webhook_secret used to verify those callbacks is returned only in this response, so store it now. It can’t be retrieved later.

Subdomains are immutable. To change a subdomain, delete it and register a new one.

See the Custom subdomain setup guide for the full flow.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Version · string · required

Management API version.

Body

application/json

subdomain · string · required

The FQDN to register as a custom subdomain.

Maximum string length: 64

Example:

"metrics.yourwebsite.com"

webhook_url · string

HTTPS URL that receives a signed POST callback each time the subdomain status changes, removing the need to poll GET /subdomains/{id}. The URL must be publicly reachable — IP addresses, custom ports and hosts resolving to private networks are rejected. Deliveries are signed; see webhook_secret in the create response for the verification scheme.

Maximum string length: 2048

Example:

"https://customer.com/hooks/fp-subdomain"

Response

201

application/json

Subdomain created.

data · object · required

Show child attributes