Provider API

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:

HeaderValue
site-idSPP
AuthorizationBearer <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 pathWhat it does
GET /jobsHeld jobs, open offers and recent declines in the member's scope
GET /jobs/:jobIdOne job: its items, stage, panels, option lists and allowedActions
POST /jobs/:jobId/acceptAccept 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/rejectDecline with a reason code from the job's option list; a note is required for Other
POST /jobs/:jobId/offer/extension-requestAsk for more time on the offer, once. Granted or refused by SureBright; the clock does not pause while it waits
PUT /jobs/:jobId/technicianSet the tentative technician on an offer, or the assignee after acceptance

Scheduling and visits#

Method and pathWhat it does
GET /jobs/:jobId/visit/slotsThe slot picker: the windows a technician could be offered
POST /jobs/:jobId/visit/proposePropose arrival windows to the customer. A technician must be assigned. The customer confirms or counters through a link
DELETE /jobs/:jobId/visit/proposalWithdraw the open proposal
POST /jobs/:jobId/visit/bookBook a slot agreed with the customer by phone
POST /jobs/:jobId/visit/rescheduleReschedule with a reason: propose new windows or book one
POST /jobs/:jobId/visit/eventsRecord en route, check in and check out
GET /scheduleThe member's visits; a Technician sees only their own

Execution#

Method and pathWhat it does
POST /jobs/:jobId/items/:itemId/scanRecord the unit scan
PUT /jobs/:jobId/inspection/draftSave the inspection draft
POST /jobs/:jobId/faultsReport an additional fault
POST /jobs/:jobId/unrepairableReport the unit cannot be repaired
POST /jobs/:jobId/parts, PATCH/DELETE /jobs/:jobId/parts/:partIdAdd, change or remove a part
POST /jobs/:jobId/parts/:partId/order, /reorder, /dropReport a part ordered, reorder it, or drop it
POST /jobs/:jobId/estimate, PUT /jobs/:jobId/estimateSubmit the estimate; revise it once with a reason
POST /jobs/:jobId/spend-requestsAsk to overrun a pre-authorised envelope
POST /jobs/:jobId/holds, POST /jobs/:jobId/holds/:holdId/clearPlace the job on hold (waiting for parts, awaiting customer, cure or rest, other) and lift it
POST /jobs/:jobId/extend-timelineAsk for more time on the repair
POST /jobs/:jobId/reportReport a problem on the job
POST /jobs/:jobId/cancelHand the job back with a reason; blocked while a hold is open
POST /jobs/:jobId/mailin/received, /mailin/start-repairMail-in jobs: the unit arrived, the bench repair started

Files and completion#

Method and pathWhat it does
POST /jobs/:jobId/files, POST /jobs/:jobId/files/:fileId/confirm, GET /jobs/:jobId/files/:fileId/urlCreate 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/:photoIdThe job's photographs
PUT /jobs/:jobId/service-reportSave the service report
PUT /jobs/:jobId/items/:itemId/outcomeRecord each item's outcome
POST /jobs/:jobId/signatureThe customer's on-device signature
GET /jobs/:jobId/completionWhat is still needed before the job can be completed
POST /jobs/:jobId/completeComplete 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-summaryThe repair summary

Invoices and billing#

Method and pathWhat it does
GET /invoices, GET /invoices/:invoiceId, GET /invoices/:invoiceId/downloadThe member's invoices
PUT /invoices/:invoiceId/linesEdit the draft's lines, with a reason code and the version you read
POST /invoices/:invoiceId/submitSubmit 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/invoicePayout history and remittances. Owner only

Unit returns#

Method and pathWhat it does
GET /unit-returns, GET /unit-returns/:unitReturnIdUnits the store still holds after a job ended and must ship back
GET /unit-returns/:unitReturnId/label-urlThe return label
POST /unit-returns/:unitReturnId/shippedMark it shipped
POST /unit-returns/transfers/:jobShipmentId/receivedReceive 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.