propgate docs

API reference › Domains › Register domain

Register a domain

POST/v1/domainspropgate domains add <domain> --profile <key> [--external-id <id>]

A write, not a check. Registering a domain does not touch DNS — it starts pending with no result, and stays that way until something calls verify on it. Registration and verification are separate calls on purpose: importing ten thousand domains must not fire ten thousand DNS runs as a side effect of a bulk insert.

FieldTypeDescription
name*stringThe domain to track.
profile*stringThe profile key to pin this domain to. Must already exist, or this call is a 422.
externalIdstringYour own identifier for this domain, unique per account. Re-sending one you already used returns the existing domain rather than erroring, and meta.created tells the two apart.
curl -s -X POST https://api.propgate.dev/v1/domains \
  -H "authorization: Bearer pg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H 'content-type: application/json' \
  -d '{"name":"yourdomain.dev","profile":"sending","externalId":"cust_1"}'
{
  "data": {
    "createdAt": "2026-08-03T12:00:00.000Z",
    "externalId": "cust_1",
    "id": "019fcf7a-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
    "lastCheckedAt": null,
    "name": "yourdomain.dev",
    "object": "domain",
    "profileVersionId": "019fcf6b-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "requirements": null,
    "requirementsMet": null,
    "requirementsTotal": null,
    "state": "pending",
    "verdict": null
  },
  "error": null,
  "meta": {
    "created": true
  }
}

externalId is your retry key: sending the same one again does not create a second row, it returns the domain that already exists. meta.created is what lets your retry logic tell "this is the customer I already had" from "this is a new one" without keeping a mapping table of its own.

Registering a name that already exists under a different external id is a 409 — that would be two records of one domain, and quietly returning one of them would hide it:

{
  "data": null,
  "error": {
    "message": "yourdomain.dev is already registered as 019fcf7a-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
  },
  "meta": null
}