> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upwell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get customer document requirements and shipper rules

> Read the customer’s effective Required Documents and Shipper Rules settings, combining organization defaults and customer overrides. Uses the existing API key and customer/rule read permissions. See [Customer requirements](/api-guides/customer-requirements) for inheritance, conditional checks, examples, and error handling. This is a settings read, not an invoice missing-documents verdict. Missing, archived, and inaccessible customers return HTTP 200 with customerRequirements: null. Hasura may return HTTP 200 with an errors body when the remote resolver fails; check for errors and a non-null result. Unauthorized roles are rejected.

> [!NOTE]
>
> Read the [Customer requirements guide](https://docs.upwell.com/api-guides/customer-requirements.md) before interpreting conditional checks or customer waivers.


## OpenAPI

````yaml /api-reference/openapi.json get /api/rest/customers/{id}/requirements
openapi: 3.1.0
info:
  description: >-
    Upwell is Accounts Receivable automation software for the logistics
    industry. We serve freight brokers, carriers, factors, and anyone who needs
    to get transportation invoices paid.


    Learn more at:


    - [Upwell.com](https://upwell.com)
  title: Upwell REST API
  version: 3.47.2
  termsOfService: https://upwell.com/legal
  contact:
    name: Upwell
    url: https://upwell.com
    email: contact@upwell.com
servers:
  - url: https://api.upwell.com
    description: Production server
  - url: https://staging.api.upwell.com
    description: Staging server
security:
  - ApiKeyAuth: []
tags:
  - name: Addresses
    description: >-
      **Core.** A typed physical address owned by one parent record — a
      customer, carrier, company, contact, or a shipment's pickup/consignee
      slot. Addresses are **not** shared master data: they are never
      deduplicated by content, and they carry no
      `sourceSystem`/`sourceSystemId`, so store the returned `addr_` id
      yourself. Embed an address when you create its parent; update it in a
      separate call. See [Working with addresses](/conventions/addresses).
  - name: Bill Line Items
    description: >-
      **Accounts payable.** Priced rows on a bill. Create, update, and delete
      only — there is no list endpoint, so read them through the parent bill.
  - name: Bill Payments
    description: >-
      **Accounts payable.** A payment that settles what you owe a carrier. A
      bill payment has no direct link to a bill — the relationship runs through
      its line items. See [Recording carrier
      payments](/api-guides/carrier-invoice-submission#recording-carrier-payments).
  - name: Bills
    description: >-
      **Accounts payable.** The expected payable synced from your TMS — what
      Upwell audits an incoming carrier invoice against. A bill is owed to
      *either* a carrier *or* a vendor, never both. See [Syncing foundation
      entities](/api-guides/syncing-foundation-entities).
  - name: Carrier Invoice Approval Requests
    description: >-
      **Accounts payable.** A pending approval decision Upwell hands to your
      system to resolve. See [Responding to an approval
      request](/api-guides/carrier-invoice-approval).
  - name: Carrier Invoice Documents
    description: >-
      **Accounts payable.** Documents attached to a carrier invoice — the
      invoice scan, BOL, POD, notice of assignment. Listed separately from
      **Carrier Invoices** because these operate on the document list rather
      than the invoice record itself.
  - name: Carrier Invoices
    description: >-
      **Accounts payable.** What a carrier actually billed you — the received
      payable, as opposed to the expected **Bill**. Create is de-duplicated
      **asynchronously**, not on the request, so a retry can briefly create a
      live duplicate: read
      [Re-submitting](/api-guides/carrier-invoice-submission#re-submitting)
      before you build retry logic.
  - name: Carrier Payment Line Items
    description: >-
      **Accounts payable.** How a bill payment splits across the bills it
      settles — the payables counterpart to **Customer Payment Line Items**.
      Build against `billId`. `billPaymentId` is **not** writable over the API
      by any role — the column exists on the table but is granted to none of
      them, so it is not part of the public insert input.
  - name: Carriers
    description: >-
      **Core.** Who hauls the freight and gets paid. Unlike customers,
      re-posting an existing `(sourceSystem, sourceSystemId)` pair **silently
      succeeds without updating any other field** — use `PUT` to change an
      existing carrier. See [Syncing foundation
      entities](/api-guides/syncing-foundation-entities).
  - name: Companies
    description: >-
      **Core.** **Your own** legal-entity or division record — *not* a customer.
      If you are looking for the party you bill and collect from, use
      **Customers** instead. Most integrations need only one company and rarely
      touch this endpoint.
  - name: Customer Payment Line Items
    description: >-
      **Accounts receivable.** How one customer payment splits across the
      invoices it pays — the unit that makes cash application work when a single
      check covers many invoices.
  - name: Customer Payments
    description: >-
      **Accounts receivable.** An incoming remittance from a customer, applied
      to invoices through its line items. Line-item amounts need not sum to the
      payment total — a remittance can be partially applied and reconciled
      later. See [Recording customer payments](/api-guides/customer-payments).
  - name: Customers
    description: >-
      **Core.** Who you bill and collect from (the shipper). Re-posting an
      existing `(sourceSystem, sourceSystemId)` pair returns `400 Uniqueness
      violation` — use `PUT` to update. **Deleting a customer also deletes their
      invoices**, so deactivate rather than delete.
  - name: Document Reference Specifications
    description: >-
      **Core.** Per-customer (or tenant-wide) rules describing what a reference
      number should look like, used to validate a reference's label and format.
      A niche configuration object that most integrations never need to touch.
  - name: Documents
    description: >-
      **Core.** A file — BOL, POD, rate confirmation, invoice scan. Usually
      attached to a shipment, invoice, or carrier invoice, though purchase
      orders and vendor invoices are uploaded standalone. Use the [two-step
      presigned-URL
      flow](/conventions/documents#document-upload-two-step-presigned-url) for
      anything large or unclassified.
  - name: Invoice Approval
    description: >-
      **Accounts receivable.** Queue and approval endpoints for customer
      invoices awaiting sign-off before they are delivered.
  - name: Invoice Documents
    description: >-
      **Accounts receivable.** Documents attached to a customer invoice.
      Documents already on a linked shipment appear on the invoice
      automatically, so you usually do not need to upload them twice.
  - name: Invoice Line Items
    description: >-
      **Accounts receivable.** Priced rows on a customer invoice — line haul,
      fuel surcharge, accessorials. They sum to the invoice total.
  - name: Invoice Shipments
    description: >-
      **Accounts receivable.** The link between a customer invoice and the
      shipments it bills. Use these endpoints to add or remove a shipment
      **after** the invoice already exists; linking or unlinking triggers a
      background re-sync of that shipment's documents onto the invoice.
  - name: Invoices
    description: >-
      **Accounts receivable.** What you bill your customer. An unqualified
      "invoice" always means this one — the customer/AR invoice, never the
      carrier's. See [Managing customer
      invoices](/api-guides/customer-invoices).
  - name: Purchase Orders
    description: >-
      **Accounts payable.** Inbound customer purchase orders parsed from a
      standalone PDF upload, including combined PDFs that Upwell splits into one
      record per document. See [Purchase orders and vendor
      invoices](/api-guides/purchase-orders-and-vendor-invoices).
  - name: Rules
    description: >-
      **Core.** Configurable if-this-then-that policies Upwell evaluates during
      processing — require a document, raise an exception, route by SCAC. Which
      fields you populate depends on the rule's `type`; see [Rules: three
      shapes](/conventions/rules).
  - name: Shipment Documents
    description: >-
      **Core.** Documents attached to a shipment. These propagate to invoices
      linked to that shipment, so uploading once is usually enough. See [Working
      with shipment documents](/api-guides/shipment-documents).
  - name: Shipment Line Items
    description: >-
      **Core.** Cargo and freight metadata on a shipment — commodity
      description, NMFC class, handling units, package counts, weight, hazmat
      flag. **Not** priced rows: unlike invoice, bill, and payment line items,
      these carry no rate or amount field at all.
  - name: Shipments
    description: >-
      **Core.** The freight movement (load) — the hub that invoices, bills, and
      documents hang off. `shipmentId` is required and has no server default.
      Pickup and consignee addresses can be embedded on create or attached later
      via `pickupAddressId`/`consigneeAddressId` on update — both are accepted
      even though this reference currently under-reports the update input. See
      [Working with addresses](/conventions/addresses).
  - name: Stops
    description: >-
      **Core.** Ordered points on a shipment's route — pickup, delivery,
      terminal, cross-dock. Populate `stopType`; the separate constrained `type`
      field is only partially adopted in practice. Deleting a shipment deletes
      its stops.
  - name: Vendor Invoices
    description: >-
      **Accounts payable.** Generic, non-freight vendor AP invoices parsed from
      a standalone PDF upload, matched to a **Purchase Order** when one exists.
      See [Purchase orders and vendor
      invoices](/api-guides/purchase-orders-and-vendor-invoices).
  - name: Vendors
    description: >-
      **Accounts payable.** A payable party that isn't a hauling carrier — a
      lumper service, a factor, a non-freight supplier. Both `sourceSystem` and
      `sourceSystemId` are required. Delete is **permanent** (there is no soft
      delete) and fails while any bill still references the vendor.
paths:
  /api/rest/customers/{id}/requirements:
    get:
      tags:
        - Customers
      summary: Get customer document requirements and shipper rules
      description: >-
        Read the customer’s effective Required Documents and Shipper Rules
        settings, combining organization defaults and customer overrides. Uses
        the existing API key and customer/rule read permissions. See [Customer
        requirements](/api-guides/customer-requirements) for inheritance,
        conditional checks, examples, and error handling. This is a settings
        read, not an invoice missing-documents verdict. Missing, archived, and
        inaccessible customers return HTTP 200 with customerRequirements: null.
        Hasura may return HTTP 200 with an errors body when the remote resolver
        fails; check for errors and a non-null result. Unauthorized roles are
        rejected.
      operationId: getCustomerRequirements
      parameters:
        - description: >-
            Upwell customer ID. Resolve it through the customer API when
            starting with a source-system ID.
          in: path
          name: id
          schema:
            type: string
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  customerRequirements:
                    title: CustomerRequirements
                    description: >-
                      Effective settings, or null for a missing/inaccessible
                      customer.
                    anyOf:
                      - $ref: '#/components/schemas/CustomerRequirements'
                      - type: 'null'
                type: object
                description: Settings response.
              examples:
                effectiveSettings:
                  $ref: '#/components/examples/CustomerRequirements'
          description: >-
            Resolved settings, or null when the customer is not visible. Check
            for body-level errors before using the result.
        '400':
          description: Request or role rejected by the API.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    CustomerRequirements:
      type: object
      description: Effective settings for one accessible customer.
      required:
        - customerId
        - documentRequirements
        - shipperRules
      properties:
        customerId:
          type: string
          description: Upwell customer ID.
        documentRequirements:
          allOf:
            - $ref: '#/components/schemas/CustomerDocumentRequirements'
          description: Resolved receivable and carrier settings.
        shipperRules:
          type: array
          description: Effective shipper rules, including disabled and overridden rules.
          items:
            $ref: '#/components/schemas/CustomerShipperRule'
      nullable: false
    CustomerDocumentRequirements:
      type: object
      description: Resolved requirements grouped by invoice workflow.
      required:
        - receivable
        - carrier
      properties:
        receivable:
          type: array
          description: >-
            Customer-invoice requirements, including unclassified-document
            holds.
          items:
            $ref: '#/components/schemas/CustomerDocumentRequirement'
        carrier:
          type: array
          description: >-
            Carrier-invoice requirements, including signed-by and
            additional-document checks.
          items:
            $ref: '#/components/schemas/CustomerDocumentRequirement'
      nullable: false
    CustomerShipperRule:
      type: object
      description: >-
        One effective global or customer shipper rule. Suppressed rules remain
        visible with enabled=false.
      required:
        - id
        - name
        - description
        - enabled
        - source
        - overrideRuleId
        - condition
      properties:
        id:
          type: string
          description: Stable effective rule ID. Overrides retain the global rule ID.
        name:
          type:
            - string
            - 'null'
          description: >-
            Saved rule name, or null when absent. Pure NEVER override markers
            retain the original global name.
        description:
          type:
            - string
            - 'null'
          description: >-
            Saved description, falling back to the saved English summary, then
            null. No description is generated at request time.
        enabled:
          type: boolean
          description: >-
            Effective enabled state, including NEVER suppression. Matched
            overrides retain the global enabled toggle, matching current
            application evaluation.
        source:
          type: string
          description: >-
            Global when inherited; customer for an override or customer-only
            rule.
          enum:
            - global
            - customer
        overrideRuleId:
          type:
            - string
            - 'null'
          description: Matched customer override row ID, or null.
        condition:
          type:
            - string
            - 'null'
          description: >-
            Effective stored rule condition. Arbitrary rules remain conditional
            expressions and are not converted into document lists.
      nullable: false
    CustomerDocumentRequirement:
      type: object
      description: >-
        One setting from the Required Documents tabs. Absent settings are
        explicitly disabled.
      required:
        - exceptionType
        - documentTypes
        - enabled
        - status
        - source
        - ruleId
        - overrideRuleId
        - configuration
        - applicability
      properties:
        exceptionType:
          type: string
          description: >-
            Stable application check identifier, such as
            CUSTOMER_INVOICE_MISSING_BOL.
        documentTypes:
          type: array
          description: >-
            Relevant document types. For standard checks, alternatives may
            satisfy the same requirement; read applicability. Additional
            required-document checks require every listed type, with
            scale/weight-ticket equivalence. Empty for signature and
            unclassified-document checks.
          items:
            type: string
        enabled:
          type: boolean
          description: >-
            Resolved rule toggle, including an explicit false customer waiver.
            An enabled additional-document check with no configured types
            imposes no requirement.
        status:
          type: string
          description: >-
            Baseline setting: required, conditional (charge/mode/config
            dependent), or not_required. Required is still subject to
            applicability exemptions and is not an invoice verdict.
          enum:
            - required
            - conditional
            - not_required
        source:
          description: >-
            Customer when a customer row controls the setting, global when
            inherited, null when no rule exists.
          anyOf:
            - type: string
              enum:
                - global
                - customer
            - type: 'null'
        ruleId:
          type:
            - string
            - 'null'
          description: >-
            Effective evaluator rule ID; carrier overrides retain the global
            rule ID. Null for an absent setting.
        overrideRuleId:
          type:
            - string
            - 'null'
          description: >-
            Customer override row ID when it replaces a global rule; null for
            inherited, customer-only, or absent settings.
        configuration:
          description: >-
            Effective saved configuration. Receivable snapshots replace global
            configuration; carrier settings use the existing merge behavior.
          anyOf:
            - $ref: '#/components/schemas/CustomerRequirementConfiguration'
            - type: 'null'
        applicability:
          type: string
          description: >-
            Human-readable scope, alternatives, and exemptions. Conditional
            requirements must not be treated as unconditional document requests.
      nullable: false
    CustomerRequirementConfiguration:
      type: object
      description: >-
        Effective saved rule configuration after app override resolution.
        Optional fields retain application defaults; this does not evaluate an
        invoice.
      properties:
        skipBolForTonuTordLoads:
          type: boolean
          description: >-
            Receivables BOL exemption for TONU/TORD charges. Omitted means
            false.
        acceptSignedPod:
          type: boolean
          description: >-
            Customer-only receivables BOL alternative: accept qualifying signed
            POD. Omitted means false; a global value does not enable this
            alternative.
        skipPodForTonuTordLoads:
          type: boolean
          description: POD exemption for TONU/TORD charges. Omitted means false.
        skipPodForOceanFreight:
          type: boolean
          description: >-
            Receivables POD exemption when every linked shipment is ocean
            freight. Omitted means false.
        requirePodForEachStop:
          type: boolean
          description: >-
            Carrier POD per-stop validation. Omitted preserves the existing
            application default.
        requireSignature:
          type: boolean
          description: >-
            Legacy carrier POD signature toggle; podRiskProfile takes
            precedence. True maps to STRICT, false or absent maps to
            NO_SIGNATURE_REQUIRED when no profile is set.
        podRiskProfile:
          type: string
          description: >-
            Saved POD profile. For receivables only an explicit customer profile
            overrides inherited document marking; an absent profile stays
            absent.
          enum:
            - NO_SIGNATURE_REQUIRED
            - LOOSE
            - MEDIUM
            - STRICT
        podAddressMatchMode:
          type: string
          description: >-
            Carrier POD address comparison mode. Omitted preserves legacy
            matching.
        podDocumentTypes:
          type: array
          description: Configured eligible carrier POD document types.
          items:
            type: string
        requiredDocumentTypes:
          type: array
          description: >-
            Additional carrier document types. The documentTypes result filters
            invalid values and duplicates.
          items:
            type: string
      nullable: false
  examples:
    CustomerRequirements:
      summary: Customer waiver and inherited shipper rule
      value:
        customerRequirements:
          customerId: cus_example
          documentRequirements:
            receivable:
              - exceptionType: CUSTOMER_INVOICE_MISSING_BOL
                documentTypes:
                  - BILL_OF_LADING
                enabled: false
                status: not_required
                source: customer
                ruleId: rul_waiver
                overrideRuleId: rul_waiver
                configuration: null
                applicability: >-
                  BOL; configuration may exempt TONU/TORD loads or allow a
                  signed POD (customer override only). Prepaid invoices and
                  invoices delivered outside Upwell are exempt.
            carrier: []
          shipperRules:
            - id: rul_shipper
              name: Signed paperwork
              description: Supply signed paperwork
              enabled: true
              source: global
              overrideRuleId: null
              condition: ALWAYS
  responses:
    UnauthorizedError:
      description: >-
        Missing, invalid, or revoked API key. The body is a flat authentication
        error object.
      content:
        application/json:
          schema:
            type: object
            required:
              - error
              - path
              - code
            properties:
              error:
                type: string
                description: Human-readable authentication error message.
              path:
                type: string
                description: Hasura error path (normally `$` for authentication failures).
              code:
                type: string
                description: Machine-readable category (`access-denied`).
          example:
            error: Authentication hook unauthorized this request
            path: $
            code: access-denied
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your API key, sent in the `Authorization` header: `Authorization:
        YOUR_API_KEY`. A `Bearer ` prefix is also accepted (`Authorization:
        Bearer YOUR_API_KEY`). Keys are created in the Upwell dashboard (Account
        → API keys) and are scoped to one organization.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.