Skip to content
builders.ac

Provisioning API · Internal testing only

connectDomains

POST
/workspaces/{wsp}/domains/connect
curl --request POST \
  --url https://api.builders.ac/api/provisioning/v1alpha1/workspaces/wsp_01k5n2rf8bd3xa9e7m4jt6vq5h/domains/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "domains": [ { "name": "northwind-outbound.com", "external_id": "crm-8421" } ] }'

Connect domains you already own into a workspace. Up to 50 per call, all or nothing: one unusable name refuses the whole batch. A name your account already holds answers 409 domain_already_exists with the id that holds it; a name held elsewhere on the platform answers 409 domain_unavailable and never says by whom. Each domain reserves 50 mailbox slots, so an account past its plan answers 409 resource_quota_exceeded. An account that has not yet been allocated DNS capacity answers 409 account_not_provisioned; it is retryable and usually clears within a few minutes.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
wsp
required
string
>= 30 characters <= 30 characters /^[wW][sS][pP]_[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}$/

Workspace TypeIDs are accepted case-insensitively. Responses use canonical lowercase.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7E]+$/

A client-generated key containing 1–255 printable ASCII characters (0x20 through 0x7E). Reuse it only for exact retries of one logical request.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
domains
required
Array<object>
>= 1 items <= 50 items
object
name
required
string
<= 253 characters
external_id
string | null
<= 255 characters

Responses

Section titled “Responses”

202

Section titled “202”

Accepted. Poll the operation.

Media typeapplication/json
object
id
required

Canonical lowercase TypeID.

string
>= 29 characters <= 29 characters /^op_[0-7][0-9a-hjkmnp-tv-z]{25}$/
object
required
Allowed value: operation
workspace_id
required

Canonical lowercase TypeID.

string
>= 30 characters <= 30 characters /^wsp_[0-7][0-9a-hjkmnp-tv-z]{25}$/
parent_operation_id

Nearest ancestor public Operation which caused this child Operation. Omitted on root Operations.

string
>= 29 characters <= 29 characters /^op_[0-7][0-9a-hjkmnp-tv-z]{25}$/
type
required
Allowed value: domain.connect
state
required
string
Allowed value: pending
done
required
target
required
object
type
required
Allowed value: domain
ids
required
Array<string>
>= 1 items <= 100 items unique items
metadata
required
object
domains
required
Array<object>
>= 1 items <= 100 items
object
id
required

Canonical lowercase TypeID.

string
>= 30 characters <= 30 characters /^dom_[0-7][0-9a-hjkmnp-tv-z]{25}$/
name
required
string
>= 1 characters <= 253 characters
state
required
string
Allowed values: pending provisioning awaiting_nameservers active failed deprovisioning deprovisioned
created_at
required
string format: date-time
started_at
string format: date-time
finished_at
string format: date-time
cancel_requested_at

Cancellation was requested. It is honoured only at a safe boundary, so keep polling state and done to learn whether it took effect.

string format: date-time
update_by_date
required

Next date by which meaningful progress should be visible.

string format: date-time
completion_by_date
required

Public completion SLA for this Operation.

string format: date-time
Example
{
  "id": "op_01k5nd7v2qe9ma4bt3rz8hy6xw",
  "object": "operation",
  "workspace_id": "wsp_01k5n2rf8bd3xa9e7m4jt6vq5h",
  "parent_operation_id": "op_01k5nf4b8yt3qd7vm2ae9rz6hx",
  "type": "domain.connect",
  "state": "pending",
  "done": false,
  "target": {
    "type": "domain",
    "ids": [
      "dom_01k5nb3wz7q2hj8vd4rt6ye9ma"
    ]
  },
  "metadata": {
    "domains": [
      {
        "id": "dom_01k5nb3wz7q2hj8vd4rt6ye9ma",
        "name": "northwind-outbound.com",
        "state": "pending"
      }
    ]
  },
  "created_at": "2026-04-15T09:15:04Z",
  "update_by_date": "2026-04-15T09:45:04Z",
  "completion_by_date": "2026-04-15T10:15:04Z"
}

Headers

Section titled “Headers”
Location
string format: uri
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

400

Section titled “400”

Idempotency key required. The example shows idempotency_key_required.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_key_required",
  "title": "Idempotency key required",
  "status": 400,
  "detail": "This request requires a valid Idempotency-Key header.",
  "code": "idempotency_key_required",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

401

Section titled “401”

Authentication required. The example shows authentication_required; this status is also answered with invalid_api_key. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "detail": "Provide an active Provisioning API Key as a Bearer token.",
  "code": "authentication_required",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

403

Section titled “403”

Account inactive. The example shows account_inactive; this status is also answered with insufficient_proof. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/account_inactive",
  "title": "Account inactive",
  "status": 403,
  "detail": "This account is inactive.",
  "code": "account_inactive",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

404

Section titled “404”

Not found. The example shows not_found.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "not_found",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

409

Section titled “409”

The connect was refused atomically, so no name in the batch was connected. The problem code says which boundary stopped it; domains lists the names at fault, and the quota members the slot arithmetic.

Media typeapplication/problem+json
One of:
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
type
required
title
required
Allowed value: Domain already connected
status
required
Allowed value: 409
code
required
Allowed value: domain_already_exists
retryable
required
detail
required
Allowed value: Your account already holds a live domain for one of these names; `domains` lists them with the id of the row that holds each. Address the existing domain instead of connecting it again.
domains
required
Array<object>
>= 1 items

A name from the request the account already holds, with the id of the Domain that holds it.

object
name
required
string
<= 253 characters
domain_id
required

Canonical lowercase TypeID.

string
>= 30 characters <= 30 characters /^dom_[0-7][0-9a-hjkmnp-tv-z]{25}$/
Examples

Domain already connected

{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/domain_already_exists",
  "title": "Domain already connected",
  "status": 409,
  "detail": "Your account already holds a live domain for one of these names; `domains` lists them with the id of the row that holds each. Address the existing domain instead of connecting it again.",
  "code": "domain_already_exists",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3",
  "domains": [
    {
      "name": "northwind-outbound.com",
      "domain_id": "dom_01k5nb3wz7q2hj8vd4rt6ye9ma"
    }
  ]
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

422

Section titled “422”

Validation failed. The example shows validation_error; this status is also answered with idempotency_mismatch, invalid_sealed_value, mailbox_upload_unavailable, provider_credentials_invalid, domains_not_bound, sequencer_targets_mixed. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/validation_error",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more request fields are invalid.",
  "code": "validation_error",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3",
  "errors": {
    "display_name": [
      "The display name must not be blank."
    ]
  }
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

429

Section titled “429”

Rate limit exceeded. The example shows rate_limit_exceeded.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests were made for this policy.",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3",
  "retry_after": "2026-04-15T09:16:04Z"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

503

Section titled “503”

Service unavailable. The example shows service_unavailable; this status is also answered with encryption_keys_unavailable, provider_unreachable. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/service_unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "Retry the request later; the service is temporarily unavailable.",
  "code": "service_unavailable",
  "retryable": true,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.