Onboarding a Customer

This walkthrough covers creating a new customer from address lookup through job completion.

Prerequisites

Valid API key and secret — Authentication
UK customer address (postcode lookup supported)

Step 1 — Look up address (recommended)

GET /v2/addresses/lookup?postcode=SW1A%202AA
Authorization: Bearer <token>

Use returned fields in the create payload address object (posttown, postcode, street, buildingname, etc.).

Note: If summaryline is omitted, the API builds one from the address parts. If uniquedeliverypointreferencenumber is omitted, a UUID is generated automatically.

Step 2 — Create the customer

POST /v2/customers
Content-Type: application/json
Authorization: Bearer <token>

Request structure

Section	Purpose
`company`	Customer name, contact email, contact phone
`adminUser`	First admin user — name, optional email, `numberE164` (no leading `+`)
`contract`	`term`, `type` (`Fixed` / `Rolling`), `plan`
`address`	UK address (from lookup or manual)

Example

{
    "company": {
        "name": "Acme Ltd",
        "contactEmail": "[email protected]",
        "contactNumber": "+441234567800"
    },
    "adminUser": {
        "name": "Jane Admin",
        "email": "[email protected]",
        "numberE164": "441234567801"
    },
    "contract": {
        "term": 36,
        "type": "Fixed",
        "plan": "standard"
    },
    "address": {
        "summaryline": "10 Downing Street, London, SW1A 2AA",
        "posttown": "London",
        "postcode": "SW1A 2AA",
        "street": "Downing Street",
        "number": "10"
    }
}

Admin user email rule

For plans hardware_only and hardware_only_cp, adminUser.email may be omitted.

For all other plans, adminUser.email is required — otherwise the API returns 400.

Step 3 — Track the job

Response (202):

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

Poll GET /jobs/{jobID} — see Async jobs.

When details is present on the job, it may include:

adminUserID
numberE164
destination (SIP registration details for the admin user)

Step 4 — Verify the customer

GET /v2/customers/{customerID}

Use customerID from the job response once the job references a customer, or from a customer_created webhook payload.

Step 5 — Continue setup

Numbers and users — additional users and numbers
Hardware orders — if ordering devices
Webhooks — automate notifications for customer_created

Plans and contract reference

Plan enum and contract patch rules: Plans and contracts.