Provisioning API

Retrieve an operation

GET

/operations/{operation_id}

const url = 'https://live-api.customers.ac/v1/operations/op_f47ac10b-58cc-4372-a567-0e02b2c3d479';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://live-api.customers.ac/v1/operations/op_f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  --header 'Authorization: Bearer <token>'

Returns a single operation by ID, including its individual steps and their statuses. Poll this endpoint to track the progress of an asynchronous provisioning workflow.

Authorizations

BearerAuth
senders:read

Parameters

Path Parameters

operation_id

required

string format: uuid

Example

op_f47ac10b-58cc-4372-a567-0e02b2c3d479

The unique identifier of the operation.

Responses

200

The requested operation.

application/json

object

data

required

object

required

Unique identifier for the operation.

string format: uuid

type

required

The type of async operation.

string

Allowed values: provision_sender connect_domain deprovision_sender deprovision_domain

status

required

The current status of an operation.

string

Allowed values: pending in_progress completed failed cancelled

sender_id

The sender associated with this operation, if applicable.

string | null format: uuid

domain_id

The domain associated with this operation, if applicable.

string | null format: uuid

steps

Ordered list of steps within the operation.

Array<object>

object

name

required

Machine-readable step identifier.

string

status

required

The current status of this step.

string

Allowed values: pending in_progress completed failed skipped

started_at

When this step started. null if not yet started.

string | null format: date-time

completed_at

When this step completed. null if not yet completed.

string | null format: date-time

message

A human-readable explanation of the step’s current state.

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "data": {
    "id": "op_f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "provision_sender",
    "status": "in_progress",
    "sender_id": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-03-24T10:00:00Z",
    "updated_at": "2026-03-24T10:15:00Z",
    "steps": [
      {
        "name": "assign_nameservers",
        "status": "completed",
        "started_at": "2026-03-24T10:00:01Z",
        "completed_at": "2026-03-24T10:00:03Z",
        "message": "Nameservers ns1.sending.ac and ns2.sending.ac assigned to outbound.acme.com."
      },
      {
        "name": "detect_propagation",
        "status": "in_progress",
        "started_at": "2026-03-24T10:00:03Z",
        "completed_at": null,
        "message": "Waiting for DNS propagation. Last check: 2026-03-24T10:15:00Z."
      },
      {
        "name": "provision_m365",
        "status": "pending",
        "started_at": null,
        "completed_at": null,
        "message": null
      },
      {
        "name": "create_mailboxes",
        "status": "pending",
        "started_at": null,
        "completed_at": null,
        "message": null
      }
    ]
  }
}

401

Authentication failed. The API key is missing or invalid.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

Allowed values: auth.missing_key auth.invalid_key auth.insufficient_scope rate.quota_exceeded validation.required_field validation.invalid_value resource.not_found resource.already_exists resource.not_ready server.error

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Examples

No API key provided

{
  "error": {
    "code": "auth.missing_key",
    "message": "No API key was provided. Include your key in the Authorization header: Bearer sac_live_xxxxx.",
    "doc_url": "https://docs.sending.ac/errors/auth-missing-key"
  }
}

Invalid API key

{
  "error": {
    "code": "auth.invalid_key",
    "message": "The API key provided is invalid or has been revoked.",
    "doc_url": "https://docs.sending.ac/errors/auth-invalid-key"
  }
}

403

The API key does not have the required scope for this operation.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "auth.insufficient_scope",
    "message": "Your API key does not have the 'senders:write' scope required for this operation.",
    "doc_url": "https://docs.sending.ac/errors/auth-insufficient-scope"
  }
}

404

The requested resource does not exist.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "resource.not_found",
    "message": "No sender found with ID snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890.",
    "doc_url": "https://docs.sending.ac/errors/resource-not-found"
  }
}

429

You have exceeded the rate limit. Wait and retry.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "rate.quota_exceeded",
    "message": "Rate limit exceeded. You may make 120 requests per minute. Retry after 30 seconds.",
    "doc_url": "https://docs.sending.ac/errors/rate-quota-exceeded"
  }
}

Headers

Retry-After

integer

Example

Number of seconds to wait before retrying.

X-RateLimit-Limit

integer

Example

The maximum number of requests allowed per minute.

X-RateLimit-Remaining

integer

Example

The number of requests remaining in the current window.

X-RateLimit-Reset

integer

Example

1711267260

Unix timestamp when the rate limit window resets.