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:
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.
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": ... }.messageis 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 asallowedActions, and an action not listed is refused.Idempotency. Mutating calls take an
Idempotency-Keyheader, 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 anidempotent-replayedheader); the same key with a different body is409 IDEMPOTENCY_KEY_REUSED; a retry while the first is still running is409 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
409with 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#
Scheduling and visits#
Execution#
Files and completion#
Invoices and billing#
Unit returns#
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.