CarrierScrub Batch API

openapi: 3.2.0
info:
  title: CarrierScrub Batch API
  version: 1.0.0
  summary: Check a US motor carrier's FMCSA record before a broker tenders a load.
  description: 'Each check returns a GO, CAUTION or STOP verdict with dated reason codes. Every reason states a fact FMCSA published and its date; none is a conclusion about the company. Every result names the FMCSA record it used (record_source) and that record''s date (record_as_of); the legacy record has been frozen since 2026-05-14. API keys work on every plan: on Pay-as-you-go and Small Brokerage each lookup uses one of the brokerage''s 25 free lookups that month, then a $1.00 credit, and on Agency lookups are unlimited. How to get a key is in https://carrierscrub.com/auth.md. AI assistants can use the same checks through the MCP server at https://carrierscrub.com/mcp.'
  contact:
    email: support@carrierscrub.com
    url: https://carrierscrub.com/contact
  termsOfService: https://carrierscrub.com/terms
servers:
- url: https://carrierscrub.com
security:
- apiKey: []
tags:
- name: Batch
paths:
  /v1/batch:
    post:
      operationId: batchCheck
      summary: Check a list of carriers from a CSV or XLSX file
      description: One carrier per row, by USDOT or MC number. Files over 8 MB are refused; rows past the first 1,000 are reported back as skipped rather than dropped. Up to 50 carriers per file are refreshed live from FMCSA; the rest use CarrierScrub's stored record with its date. The same carrier listed more than once is checked once. The request counts once toward the daily API limit.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: A .csv or .xlsx file.
      responses:
        '200':
          description: One result row per carrier in the file, in file order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                  filename:
                    type: string
                  results:
                    type: array
                    description: Each row carries the input value and either the carrier's verdict (the same fields as a single lookup) or the reason it could not be checked.
                    items:
                      type: object
                  usage:
                    type: object
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      tags:
      - Batch
components:
  responses:
    Error:
      description: 'The check was not completed. 401: no key, or the key is invalid, expired or revoked. 402 (code payg_credits_exhausted): the brokerage has used its free lookups this month and has no credits left; the hint says where to buy them. 404: no carrier for that number. 413: the file is too large. 429: daily limit reached. 503: FMCSA could not be reached and no dated record is on file.'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                type: string
              hint:
                type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer cs_live_... An owner or admin of the brokerage, on any plan, creates keys in Admin, then API keys. A key that goes unused for 60 days stops working.'
externalDocs:
  description: Getting access
  url: https://carrierscrub.com/auth.md