Async Jobs

Several write operations provision or change resources in the background. They respond immediately with a jobID (HTTP 202 Accepted) rather than waiting for completion.

Operations that return a jobID

Action	Method	Path
Create customer	`POST`	`/customers`
Delete customer	`DELETE`	`/customers/{customerID}`
Update contract	`PATCH`	`/customers/{customerID}/contract`

Example response

{
    "jobID": "ORD-12345-abcde"
}

Store jobID in your system before returning success to your own users.

Poll job status

Single job

GET /v2/jobs/{jobID}
Authorization: Bearer <token>

Example response:

{
    "jobID": "ORD-12345-abcde",
    "type": "New Company",
    "status": "In Progress",
    "customerID": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
        "adminUserID": "660e8400-e29b-41d4-a716-446655440001",
        "numberE164": "441234567890",
        "destination": {
            "registrationServer": "https://...",
            "sipID": "...",
            "sipPassword": "...",
            "stunPort": "...",
            "stunServer": "..."
        }
    }
}

details is populated when provisioning has progressed (admin user, number, SIP destination). It may be absent early in the job lifecycle.

List jobs

GET /v2/jobs?limit=10&offset=0
Authorization: Bearer <token>

Recommended integration pattern

Call the async endpoint and persist jobID.
Poll GET /jobs/{jobID} on an interval (with backoff) until status indicates completion or failure.
Confirm outcome with GET /customers/{customerID} or domain-specific reads (users, numbers).
Optionally subscribe to Webhooks (customer_created, contract_updated, etc.) instead of or in addition to polling.

Synchronous alternatives

These update state inline (no jobID):

Action	Method	Path
Update customer contact details	`PATCH`	`/customers/{customerID}`
Suspend customer	`POST`	`/customers/{customerID}/suspend`
Resume customer	`POST`	`/customers/{customerID}/resume`

See Customer lifecycle for when to use each.