Service Provider SDK Overview

Introduction

The Service Provider SDK exposes mobile rides, tow rides, mechanics, customers, appointments, and webhooks through one REST surface. It is designed so a partner app can move from discovery to booking to job completion without switching APIs or authentication contexts.

Most integrations follow the same path: create a session, resolve a customer, discover a mechanic or estimate a ride, create the request, then poll or listen for progress updates until the job is complete.

The SDK is intentionally split into functional groups so you can integrate only the pieces you need. For example, a roadside assistance partner may only need mobile rides and webhooks, while a workshop partner may rely heavily on mechanics, customers, and appointments.

Because every request uses the same session token and the same base URL, you can build a single API client and reuse it across the entire partner workflow. That keeps authentication, error handling, and retry logic centralized in one place.

Quick Start

• 1. Obtain your Partner Public Key from the API Keys section.
• 2. Create a session to get your JWT token.
• 3. Send the token in the Authorization: Bearer {token} header.
• 4. Explore the endpoint groups below and choose the workflow you need.

Guide Links

• Authentication - Learn how the session token is issued and refreshed
• Errors - See response formats and common failure codes
• Rate Limits - Understand request limits and retry behavior
• Create Session - Jump straight to the token endpoint
• Create Ride - Start a mobile ride flow
• Create Tow - Start a tow flow
• Create Appointment - Book a service appointment

Authentication

Exchange your Partner Public Key for a JWT session token at POST /api/v1/partner/sdk/sessions. The token is short-lived, so it should be treated as a session credential rather than a permanent API key.

Send the token in the Authorization header as Bearer ... on every protected request. When the token expires, call the session endpoint again and replace the old token before continuing API work.

The session endpoint is the bridge between your long-lived partner credentials and the short-lived token used by the API. This is safer than putting a permanent secret in every client request, and it gives you a clean place to rotate credentials server-side.

In practice, your backend should request a session, cache the token until it is close to expiry, and then renew it proactively before users notice a failure. If you are building a server-to-server integration, keep the public key and any private credentials only on the server.

What To Send

Session Tips

• Create Session - Exchange your public key for a JWT token
• Invalid token errors - The most common auth-related failure mode
• Retry behavior - Token refresh and backoff strategy

Practical Guidance

Keep the token out of your frontend source code whenever possible. A browser app should talk to your backend, and your backend should talk to QuickMechs. That keeps the Partner Public Key and session logic under your control.

If your request starts failing with 401 errors, do not assume the whole integration is broken. The most common cause is simply that the token aged out and needs to be refreshed before retrying the original request.

Use the Test environment during development, implement proper token refresh logic in your application, and validate all webhook signatures if you are consuming webhook events.

Errors

The API returns standard HTTP status codes with a JSON error payload. This gives you two signals at once: the HTTP status tells you the category of failure, and the error code tells you the specific reason.

For example, 400 usually means the payload needs to be corrected, 401 usually means the token is missing or expired, and 429 means you should slow down and retry later.

When an API call fails, inspect the HTTP status first, then read the error code and message to decide whether the request should be retried, corrected, or abandoned.

Most partner integrations benefit from a simple rule: treat 4xx responses as request or permission problems, and treat 5xx responses as transient platform issues unless the API tells you otherwise. That keeps retries from creating duplicate jobs or repeated cancellations.

Error Response Format

{
  "error": {
    "message": "Invalid session token",
    "code": "INVALID_TOKEN",
    "details": {}
  }
}

How To Handle Errors

• 400 - Fix the payload or required parameters before retrying
• 401 - Refresh the session token and retry the request
• 403 - Check account permissions and environment access
• 404 - Verify the resource reference or ID
• 429 - Back off and retry after the window resets
• 500 - Retry only if the operation is safe to repeat

When a request creates or mutates a ride, appointment, or webhook subscription, pair your retry policy with idempotency so the same action is not processed twice. That is especially important for create, cancel, and status-change requests.

For debugging, keep the raw error payload and the request context together. In practice, the combination of endpoint, status code, payload, and timestamp makes it much easier to spot whether the issue is validation, access, missing reference data, or rate limiting.

Common Error Codes

Rate Limits

Rate limits are enforced per partner account and are meant to protect both your integration and the platform. The API surfaces quota details in response headers so you can adapt dynamically instead of guessing.

Watch the rate-limit headers, back off on 429, and refresh the session token before it expires. If your app polls status endpoints frequently, add caching or longer polling intervals to stay well within the limit.

The main goal is to make your integration predictable under load. Rather than sending bursts of polling requests or retrying aggressively, spread requests out and let the response headers tell you how close you are to the limit.

Rate Limit Headers

Each API response includes rate limit information in the HTTP headers:

Recommended Strategy

• Read operations - Cache list and status responses when possible
• Write operations - Use idempotency keys on create, update, cancel, and webhook calls
• Retries - Back off exponentially after a 429 or transient 5xx response
• Sessions - Refresh tokens before the 15-minute TTL expires

A good partner integration usually polls only when needed and prefers webhooks for asynchronous updates. That approach lowers traffic, reduces latency, and makes it much less likely that you will run into the limit during busy periods.

If you build a background worker or sync job, add jitter to retry timing and avoid retry storms. A few extra seconds between attempts is usually better than hammering the API with many requests that all fail the same way.

Default Limits

- Test Environment: 100 requests per minute

- Live Environment: 1000 requests per minute

If you exceed the rate limit, you'll receive a 429 status code. Implement exponential backoff and retry your request after the Retry-After header duration.