API docs by Redocly

Ready App Partner API — TruckX Integration Preview (preview-2026-07-15)

Download OpenAPI specification:

Preview of the Ready App driver-passport document-sharing surface for the TruckX integration.

Consent model. Passport data is driver-owned. Each document carries a driver-controlled shareability flag; only documents the driver has marked shareable are visible to partners. A per-partner consent-grant model (grant/revoke/audit) ships with partner credentials.

Authentication

Endpoints shown authenticate with bearer tokens (driver-scoped JWTs in this preview). Dedicated partner credentials are being provisioned for TruckX and will work as follows (final details in the integration guide):

  • Grant: OAuth 2.0 client_credentials exchange at a dedicated partner token endpoint; your client_secret is shown once at issuance and can be rotated with an overlap window.
  • Tokens: short-lived (30-60 min) scoped bearer tokens. There are no refresh tokens; on expiry, request a new token with your client credentials.
  • Scopes: least-privilege per surface (e.g. documents:read, consent:read); tokens carry the partner id and are introspectable.

Date formats

Every date on this surface (issue_date, expiration_date) is a DD/MM/YYYY string, e.g. 27/04/2026. Zero-padding is optional (27/4/2026 is accepted). Each endpoint's description restates this next to its fields.

Error handling

Two patterns exist on this surface; every endpoint below is labeled with its pattern.

  • HTTP-signaled (most endpoints): failures return real HTTP status codes (400, 403, 404, 500) with the standard envelope body {status, status_code, message, data}.
  • Envelope-signaled (legacy upload/profile endpoints: document, certification, and endorsement upload, and get_driver_profile): the HTTP status is 200/201 even on validation failure; the authoritative outcome is status_code / status / message inside the body. Always check the body status_code on these.
  • One exception: get_driver_documents_only returns its payload directly ({key_url, ...}) rather than the envelope.

Rate limits

Partner credentials will be rate-limited per credential with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers and 429 on exceed. Final tiers ship in the integration guide; assume a conservative default (60 req/min) when designing polling.

Pagination

GET /drivers/broker-verify/companies/ paginates with page (default 1) / page_size (default 20) and returns pagination: {page, page_size, total_count, total_pages}. All other list responses on this surface return complete sets.

Versioning & changelog

The partner surface is versioned by this document's info.version; breaking changes will be announced ahead of time once partner credentials are live.

  • preview-2026-07-15 - populated request/response examples; per-endpoint date-format callouts; error-handling, auth, rate-limit, pagination, and versioning sections. Endpoint set unchanged.
  • draft-2026-07-02 - initial 12-endpoint preview.

This preview is shared under NDA, is subject to change, and is not a commitment of endpoint availability for server-to-server use until partner credentials are issued.

user_management

Upload driver documents (v2, JSON base64 or multipart)

Bulk-create DriverDocument rows. Accepts application/json with documents[].file as base64, or multipart/form-data using bracketed keys documents[0][name], documents[0][file], documents[0][issue_date], documents[0][expiration_date], documents[0][document_type_id] or documents[0][custom_document_type], documents[0][is_shareable_with_broker_shipper]. Exactly one of document_type_id / custom_document_type per item; custom types are created (or reused) per driver. is_shareable_with_broker_shipper defaults to true.

Dates: issue_date / expiration_date are DD/MM/YYYY strings (e.g. 27/04/2026; zero-padding optional, 27/4/2026 is accepted).

Error pattern: envelope-signaled. This endpoint returns HTTP 200/201 even when validation fails; read the real outcome from status_code / status / message in the response body. See Error handling in the overview.

Authorizations:
bearerAuth
Request Body schema:
required
required
Array of objects (UMBDocumentV2Item)

Responses

Request samples

Content type
{
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 201,
  • "message": "Documents uploaded successfully",
  • "data": [
    ]
}

Add driver certifications (v2)

Bulk-create DriverInstitute certification rows for the authenticated driver. Items use issue_date/expiration_date in DD/MM/YYYY. Validation errors are returned inside a 200/201 envelope (status=false, status_code=400), not as HTTP 400.

Dates: issue_date / expiration_date are DD/MM/YYYY strings (e.g. 27/04/2026; zero-padding optional, 27/4/2026 is accepted).

Error pattern: envelope-signaled. This endpoint returns HTTP 200/201 even when validation fails; read the real outcome from status_code / status / message in the response body. See Error handling in the overview.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects (UMBCertificationItem)

Responses

Request samples

Content type
application/json
{
  • "certification": [
    ]
}

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "message": "string",
  • "data": { }
}

Add driver endorsements (v2)

Bulk-create DriverEndorsement rows with issue_date and expiration_date (DD/MM/YYYY, expiration must be after issue).

Dates: issue_date / expiration_date are DD/MM/YYYY strings (e.g. 27/04/2026; zero-padding optional, 27/4/2026 is accepted).

Error pattern: envelope-signaled. This endpoint returns HTTP 200/201 even when validation fails; read the real outcome from status_code / status / message in the response body. See Error handling in the overview.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects (UMBEndorsementV2Item)

Responses

Request samples

Content type
application/json
{
  • "endorsement": [
    ]
}

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "message": "string",
  • "data": { }
}

Get the logged-in driver's full profile

Driver profile with vehicles, document type list, experiences, DOT form completion and marketing consent flags. Always returned with HTTP 200 on success. A non-driver caller gets HTTP 403 from the IsDriver permission class (the in-body 401 branch in the view is dead code behind IsDriver).

Error pattern: envelope-signaled. This endpoint returns HTTP 200/201 even when validation fails; read the real outcome from status_code / status / message in the response body. See Error handling in the overview.

Authorizations:
bearerAuth
query Parameters
tz
string
Default: "0:00"

Client timezone offset used when building documents_type list

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "message": "string",
  • "status_code": 0,
  • "data": [
    ]
}

Required-document status for the logged-in driver

Status per canonical required document type with every upload listed in uploaded_documents. Optional company_id switches the required list to that company's require_* flags (same rules as submission validation).

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
query Parameters
company_id
integer

Use this company's verification requirements instead of the full fixed list

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "data": {
    }
}

List/search broker-verify-visible companies for drivers

Pagination: page (default 1) and page_size (default 20); the response carries pagination: {page, page_size, total_count, total_pages}.

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
query Parameters
q
string

Matches company name, description, or load pickup/delivery cities

page
integer >= 1
Default: 1
page_size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "data": {
    }
}

Company detail plus its active loads for drivers

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
path Parameters
company_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "data": {
    }
}

Driver submits their profile to a broker-verify company

Validates duplicate submissions, questionnaire booleans, experience/document ownership, expiry of shared documents and required-document completeness (validate_driver_documents per company require_* flags) before creating a DriverProfileSubmission with status "Submitted".

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
Request Body schema:
required
company_id
required
integer
selected_experience_ids
Array of integers

Required (non-empty) when own_authority is false; ids must belong to the driver

shared_document_ids
Array of integers

Must belong to the driver and be unexpired

drug_test
required
boolean
own_truck
required
boolean
own_authority
required
boolean
carrier_company_id
integer or null

DriverExperience pk used as carrier reference

Responses

Request samples

Content type
{
  • "company_id": 0,
  • "selected_experience_ids": [
    ],
  • "shared_document_ids": [
    ],
  • "drug_test": true,
  • "own_truck": true,
  • "own_authority": true,
  • "carrier_company_id": 0
}

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "message": "string",
  • "data": {
    }
}

social_app

Toggle a document's broker/shipper share flag

Driver updates is_shareable_with_broker_shipper on one of their own documents. Ownership enforced.

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
Request Body schema: application/json
required
document_id
required
integer
is_shareable_with_broker_shipper
required
boolean

Responses

Request samples

Content type
application/json
{
  • "document_id": 0,
  • "is_shareable_with_broker_shipper": true
}

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "message": "string",
  • "data": {
    }
}

Get one of the driver's own documents (ownership enforced)

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
path Parameters
document_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "message": "string",
  • "data": {
    }
}

List own driver documents filtered by document type

Returns the authenticated user's DriverDocument records for a given document_type_id, with edit/delete URLs.

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
query Parameters
document_type_id
required
integer

DocumentsType primary key.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "status_code": 0,
  • "message": "string",
  • "data": {
    }
}

Merge a driver's shareable documents into a single PDF

Fetches DriverDocument files flagged shareable_with_broker_shipper for the given profile_id, merges them into one PDF in S3, and returns a presigned URL.

Response shape note: unlike every other endpoint here, the success body is NOT the standard envelope; it returns {key_url, message, skipped_files, failed_files} directly.

Error pattern: HTTP-signaled. Failures use real HTTP status codes (400/403/404/500) with the standard envelope body. See Error handling in the overview.

Authorizations:
bearerAuth
query Parameters
profile_id
required
integer

Driver Profile primary key.

Responses

Response samples

Content type
application/json
{
  • "key_url": "string",
  • "message": "string",
  • "skipped_files": [
    ],
  • "failed_files": [
    ]
}