---
title: "Provider API"
description: "The Service Provider Portal's job API for repair and installation businesses: authentication, the request conventions, and what each group of endpoints does."
---

Everything a provider does in the Service Provider Portal can be done against its API: accept an offer, schedule a visit, record an inspection, submit an estimate, complete the job and invoice it. Read this page if you run your own dispatch or field-service system and want to drive SureBright jobs from it. It summarises the surface by capability; the exact bodies are in the portal's own calls and your SureBright contact can share them.

## Base URL and authentication

The API is served under the Service Provider Portal's API host, under the prefix `/spp/v1`. Ask your SureBright contact for the host for your environment.

Every request carries two headers:

| Header | Value |
|---|---|
| `site-id` | `SPP` |
| `Authorization` | `Bearer <access token>` |

Sign in with `POST /auth/login` (email and password) to receive an access token and a refresh token. An access token lives for one hour; `POST /auth/token/refresh` exchanges the refresh token for a new pair, and `POST /auth/logout` revokes the session. `GET /me` returns the signed-in member, their business, their role on each store and the permissions the session holds.

```bash
curl -X POST "$SPP_API/spp/v1/auth/login" \
  -H "site-id: SPP" \
  -H "Content-Type: application/json" \
  -d '{"email":"owner@example.com","password":"..."}'
```

A member's role is read from SureBright on every request, so a role change, a removal or a deactivated store applies immediately. A revoked session answers `401 SESSION_REVOKED`.

## Conventions

- **Envelope.** Every response is `{ "isError": false, "data": ... }` or `{ "isError": true, "errorCode": "...", "message": "...", "details": ... }`. `message` is written to be shown to a person.
- **Scope.** Reads return only the member's own jobs, invoices and stores. A job outside the member's reach is `404 JOB_NOT_FOUND`; it is not revealed. What a member may do on a given job comes back on the job read as `allowedActions`, and an action not listed is refused.
- **Idempotency.** Mutating calls take an `Idempotency-Key` header, required on the execution routes. The key is scoped to the member, method and path, and the body is hashed with it: a retry with the same key and body replays the first answer (with an `idempotent-replayed` header); the same key with a different body is `409 IDEMPOTENCY_KEY_REUSED`; a retry while the first is still running is `409 IDEMPOTENCY_IN_PROGRESS`. Only a 2xx is stored.
- **Money and decimals** are strings. Dates and times are ISO 8601; visit times are in the job's time zone.
- **Files** never pass through the API as multipart. Create a file record, PUT the bytes to the signed URL it returns, then confirm it.
- **Stage conflicts** answer `409` with a code naming the rule: `INVALID_STAGE`, `OFFER_EXPIRED`, `OFFER_NOT_OPEN`, `STORE_AT_CAPACITY`, `TECHNICIAN_REQUIRED`, `PROPOSAL_ALREADY_OPEN`, `QUOTE_NOT_APPROVED`, `INVOICE_NOT_DRAFT`, `INVOICE_VERSION_CONFLICT`. Refetch the job and re-present.

## Endpoints by capability

Paths below are relative to `/spp/v1`.

### Jobs and offers

| Method and path | What it does |
|---|---|
| `GET /jobs` | Held jobs, open offers and recent declines in the member's scope |
| `GET /jobs/:jobId` | One job: its items, stage, panels, option lists and `allowedActions` |
| `POST /jobs/:jobId/accept` | Accept the offer. Owner or store Admin. Optional technician, start-by date, completion estimate and parts outlook. `409 OFFER_EXPIRED` after the 24-hour window, `409 STORE_AT_CAPACITY` at the store's concurrent limit |
| `POST /jobs/:jobId/reject` | Decline with a reason code from the job's option list; a note is required for **Other** |
| `POST /jobs/:jobId/offer/extension-request` | Ask for more time on the offer, once. Granted or refused by SureBright; the clock does not pause while it waits |
| `PUT /jobs/:jobId/technician` | Set the tentative technician on an offer, or the assignee after acceptance |

### Scheduling and visits

| Method and path | What it does |
|---|---|
| `GET /jobs/:jobId/visit/slots` | The slot picker: the windows a technician could be offered |
| `POST /jobs/:jobId/visit/propose` | Propose arrival windows to the customer. A technician must be assigned. The customer confirms or counters through a link |
| `DELETE /jobs/:jobId/visit/proposal` | Withdraw the open proposal |
| `POST /jobs/:jobId/visit/book` | Book a slot agreed with the customer by phone |
| `POST /jobs/:jobId/visit/reschedule` | Reschedule with a reason: propose new windows or book one |
| `POST /jobs/:jobId/visit/events` | Record **en route**, **check in** and **check out** |
| `GET /schedule` | The member's visits; a Technician sees only their own |

### Execution

| Method and path | What it does |
|---|---|
| `POST /jobs/:jobId/items/:itemId/scan` | Record the unit scan |
| `PUT /jobs/:jobId/inspection/draft` | Save the inspection draft |
| `POST /jobs/:jobId/faults` | Report an additional fault |
| `POST /jobs/:jobId/unrepairable` | Report the unit cannot be repaired |
| `POST /jobs/:jobId/parts`, `PATCH`/`DELETE /jobs/:jobId/parts/:partId` | Add, change or remove a part |
| `POST /jobs/:jobId/parts/:partId/order`, `/reorder`, `/drop` | Report a part ordered, reorder it, or drop it |
| `POST /jobs/:jobId/estimate`, `PUT /jobs/:jobId/estimate` | Submit the estimate; revise it once with a reason |
| `POST /jobs/:jobId/spend-requests` | Ask to overrun a pre-authorised envelope |
| `POST /jobs/:jobId/holds`, `POST /jobs/:jobId/holds/:holdId/clear` | Place the job on hold (waiting for parts, awaiting customer, cure or rest, other) and lift it |
| `POST /jobs/:jobId/extend-timeline` | Ask for more time on the repair |
| `POST /jobs/:jobId/report` | Report a problem on the job |
| `POST /jobs/:jobId/cancel` | Hand the job back with a reason; blocked while a hold is open |
| `POST /jobs/:jobId/mailin/received`, `/mailin/start-repair` | Mail-in jobs: the unit arrived, the bench repair started |

### Files and completion

| Method and path | What it does |
|---|---|
| `POST /jobs/:jobId/files`, `POST /jobs/:jobId/files/:fileId/confirm`, `GET /jobs/:jobId/files/:fileId/url` | Create a file record and get a signed upload URL, confirm the upload, read a signed download URL |
| `GET /jobs/:jobId/photos`, `DELETE /jobs/:jobId/photos/:photoId` | The job's photographs |
| `PUT /jobs/:jobId/service-report` | Save the service report |
| `PUT /jobs/:jobId/items/:itemId/outcome` | Record each item's outcome |
| `POST /jobs/:jobId/signature` | The customer's on-device signature |
| `GET /jobs/:jobId/completion` | What is still needed before the job can be completed |
| `POST /jobs/:jobId/complete` | Complete the job. Checks out an open visit, requires the completion floor to be met (`422 COMPLETION_FLOOR_NOT_MET` lists what is missing) and the labour figures to match the visits, and creates the invoice draft |
| `GET /jobs/:jobId/repair-summary` | The repair summary |

### Invoices and billing

| Method and path | What it does |
|---|---|
| `GET /invoices`, `GET /invoices/:invoiceId`, `GET /invoices/:invoiceId/download` | The member's invoices |
| `PUT /invoices/:invoiceId/lines` | Edit the draft's lines, with a reason code and the `version` you read |
| `POST /invoices/:invoiceId/submit` | Submit the draft. It is audited inline and comes back approved or flagged. `POST /jobs/:jobId/invoice` is an alias for the job's live draft |
| `GET /billing/history`, `GET /billing/history/:recordId/invoice` | Payout history and remittances. Owner only |

### Unit returns

| Method and path | What it does |
|---|---|
| `GET /unit-returns`, `GET /unit-returns/:unitReturnId` | Units the store still holds after a job ended and must ship back |
| `GET /unit-returns/:unitReturnId/label-url` | The return label |
| `POST /unit-returns/:unitReturnId/shipped` | Mark it shipped |
| `POST /unit-returns/transfers/:jobShipmentId/received` | Receive a transfer that arrived after the store let the job go |

### Dashboard

`GET /dashboard` (the overview), `/dashboard/action-center`, `/dashboard/earnings`, `/dashboard/earnings/stores`, `/dashboard/performance` and `/dashboard/activities`, each over a date range and optionally one store.

## Everything else

Onboarding, documents, stores, payout methods, the team and account settings are served by the same API under their own paths (`/onboarding`, `/documents`, `/compliance`, `/stores`, `/team`, `/account`, `/settings`), with the same headers and envelope. They are what the portal's own screens call; ask your SureBright contact if you need to drive them.
