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

# Create orders as a batch

> The endpoint accepts up to 10,000 orders in a single request and creates them in the background. It responds immediately with `202` and a job id — poll [the job status](/api-reference/orders/orders_batch_status) to get the result of each order.

Each order is processed on its own: valid orders are created and invalid ones are reported against their position in the request, so one bad order never blocks the rest. An order whose `order_number` already exists in the environment is reused instead of duplicated, which makes retrying a batch safe.

Rate limits count every order in the request, not the request itself. A batch of 500 orders therefore uses the same budget as 500 calls to [create an order](/api-reference/orders/orders_create).



## OpenAPI

````yaml POST /v1/orders/batch/
openapi: 3.0.1
info:
  title: Truv API
  description: Truv API Documentation
  termsOfService: https://www.truv.com/legal/terms-of-use
  contact:
    email: support@truv.com
  version: v1
servers:
  - url: https://prod.truv.com
security:
  - ClientID: []
    AccessKey: []
tags:
  - name: Users
  - name: Bridge Token
  - name: Companies and Data Providers
  - name: Key Management
  - name: Account Links
  - name: Data Refresh
  - name: Customization Templates
  - name: Webhooks
  - name: Orders
  - name: Tasks
  - name: VOIE Reports
  - name: VOA Reports
  - name: Income Insights Reports
  - name: DDS Reports
  - name: Employment
  - name: Identity
  - name: Shifts
  - name: Pay Statements
  - name: Tax Documents
  - name: Parsed Documents
  - name: Reports
  - name: Uploaded Documents
  - name: Bank Accounts
  - name: Bank Statements
  - name: Deposit Switch Reports
  - name: Insurance Reports
  - name: Income Report
  - name: Scoring Attributes
  - name: Accounts
  - name: Transactions
  - name: Recurring Transactions
  - name: Document Collections
paths:
  /v1/orders/batch/:
    parameters: []
    post:
      tags:
        - Orders
      summary: Create orders as a batch
      description: >-
        The endpoint accepts up to 10,000 orders in a single request and creates
        them in the background. It responds immediately with `202` and a job id
        — poll [the job status](/api-reference/orders/orders_batch_status) to
        get the result of each order.


        Each order is processed on its own: valid orders are created and invalid
        ones are reported against their position in the request, so one bad
        order never blocks the rest. An order whose `order_number` already
        exists in the environment is reused instead of duplicated, which makes
        retrying a batch safe.


        Rate limits count every order in the request, not the request itself. A
        batch of 500 orders therefore uses the same budget as 500 calls to
        [create an order](/api-reference/orders/orders_create).
      operationId: orders_batch_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderBatch'
        description: Orders to create, with optional defaults applied to every order
        required: true
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBatchJob'
        '400':
          description: HTTP 400 Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: HTTP 401 Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: HTTP 403 Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
components:
  schemas:
    OrderBatch:
      required:
        - orders
      type: object
      properties:
        orders:
          type: array
          minItems: 1
          maxItems: 10000
          description: >-
            Orders to create. Each item takes the same fields as a single order,
            and is validated individually when the batch runs.
          items:
            $ref: '#/components/schemas/Order'
        template_id:
          type: string
          nullable: true
          maxLength: 32
          description: >-
            Template applied to every order that does not set its own
            `template_id`.
          example: 9b96606355b94e8abff8ed8d75aa2027
        source:
          type: string
          nullable: true
          description: Source applied to every order that does not set its own `source`.
          enum:
            - floify
            - besmartee
            - lenderlogix
            - encompass_consumer_connect
            - byte
            - core_logic
            - xactus
            - constellation
            - banno
            - mx
            - q2
            - clutch
            - accio
            - encompass
            - tpo_connect
            - darkmatter
            - tazworks
            - internal
            - simplenexus
            - external_webpage
            - individual
            - alkami
            - blue_sage
            - lodasoft
            - blend
            - tidalwave
            - self_signup
          example: internal
    OrderBatchJob:
      type: object
      properties:
        id:
          type: string
          description: Batch job ID. Use it to poll the job status.
          example: 9f2c1b7e4a3d4e8fa1b2c3d4e5f60718
        status:
          type: string
          description: >-
            `pending` while orders are still being created, then `completed`
            once every order has an outcome, or `failed` if the whole job could
            not run.
          enum:
            - pending
            - completed
            - failed
          example: completed
        order_count:
          type: integer
          description: Number of orders submitted in the request.
          example: 3
        created_count:
          type: integer
          description: >-
            Number of orders that are usable, counting both `created` and
            `existing`.
          example: 2
        failed_count:
          type: integer
          description: Number of orders that could not be created.
          example: 1
        results:
          type: array
          description: >-
            Outcome of each submitted order, matched to its position in the
            request.
          items:
            $ref: '#/components/schemas/OrderBatchResult'
        errors:
          type: array
          nullable: true
          description: >-
            Why the job as a whole could not run. Set only when `status` is
            `failed`, and `null` otherwise — errors for individual orders are in
            `results[].errors` instead.
          items:
            type: object
            properties:
              detail:
                type: array
                description: Messages describing the failure.
                items:
                  type: string
          example:
            - detail:
                - The batch could not be processed.
        created_at:
          type: string
          format: date-time
          description: Time the batch was accepted.
          example: '2026-08-10T09:14:22.881Z'
        updated_at:
          type: string
          format: date-time
          description: Time the batch was last updated.
          example: '2026-08-10T09:15:04.203Z'
    Error400:
      description: ''
      type: object
      properties:
        error:
          description: ''
          type: object
          properties:
            code:
              description: ''
              type: string
              example: incorrect_parameters
            message:
              description: ''
              type: string
              example: Incorrect request parameters
            extra:
              description: ''
              type: object
              properties:
                invalid-params:
                  description: ''
                  type: array
                  items:
                    description: ''
                    type: object
                    properties:
                      field:
                        description: ''
                        type: string
                        example: access_token
                      message:
                        description: ''
                        type: string
                        example: This field is required.
                  example:
                    - field: access_token
                      message: This field is required.
    Error401:
      description: ''
      type: object
      properties:
        error:
          description: ''
          type: object
          properties:
            code:
              description: ''
              type: string
              example: authentication_failed
            message:
              description: ''
              type: string
              example: No such token
    Error403:
      description: ''
      type: object
      properties:
        error:
          description: ''
          type: object
          properties:
            code:
              description: ''
              type: string
              example: not_authenticated
            message:
              description: ''
              type: string
              example: Authentication credentials were not provided.
    Order:
      required:
        - products
        - first_name
        - last_name
      type: object
      properties:
        products:
          description: Types of products selected for the order
          type: array
          example:
            - income
          items:
            type: string
            enum:
              - income
              - employment
              - deposit_switch
              - pll
              - insurance
              - transactions
              - assets
            default: employment
        first_name:
          description: First name
          type: string
          example: John
          maxLength: 50
        last_name:
          description: Last name
          type: string
          example: Doe
          maxLength: 50
        ssn:
          description: >-
            User's SSN — the full 9 digits or the last 4 digits. Dashes and
            spaces are accepted on input and stripped before storing; any other
            format is rejected.
          type: string
          example: '222233333'
        email:
          description: Subject's email
          type: string
          format: email
        phone:
          description: >-
            Subject's phone number. A 10-digit US number; accepted formats are
            normalized and stored as E.164 (`+14155554193`).
          type: string
          example: '4155554193'
        order_number:
          description: External ID for the order.
          type: string
          example: '1534332'
          maxLength: 512
        external_user_id:
          description: >-
            External user identifier. If not provided, order_number will be used
            for backwards compatibility.
          type: string
          maxLength: 512
          example: user_12345
          nullable: true
        employers:
          description: List of employers
          type: array
          items:
            $ref: '#/components/schemas/EmployerCreate'
        financial_institutions:
          description: List of financial institutions
          type: array
          items:
            $ref: '#/components/schemas/FinancialInstitutionCreate'
          maxItems: 5
        insurance:
          $ref: '#/components/schemas/InsuranceCreate'
        manager:
          type: object
          required:
            - email
          properties:
            email:
              description: Email of the order manager
              type: string
              example: john.doe@example.com
              maxLength: 255
            name:
              description: Name of the order manager
              type: string
              example: John Doe
              maxLength: 600
          description: Associate your order manager info with an order.
        loan:
          $ref: '#/components/schemas/Loan'
        reports:
          $ref: '#/components/schemas/CreateReports'
        template_id:
          description: ID of the template
          type: string
          example: 9b96606355b94e8abff8ed8d75aa2027
          maxLength: 32
        custom_field:
          description: >-
            Client provided custom field. Must be enabled in the dashboard
            customization section.
          type: string
          maxLength: 255
        cc_emails:
          description: >-
            A list of email addresses that will receive carbon copies (CC) of
            order status updates.
          type: array
          items:
            type: string
            format: email
          maxItems: 15
        notes:
          description: Free text field for notes associated with the order
          type: string
          example: To be processed by John Doe
          nullable: true
          minLength: 1
          maxLength: 2000
        source:
          description: Type of the platform (internal, accio, etc.)
          type: string
          example: floify
          enum:
            - floify
            - besmartee
            - lenderlogix
            - encompass_consumer_connect
            - byte
            - core_logic
            - xactus
            - constellation
            - banno
            - mx
            - q2
            - clutch
            - accio
            - encompass
            - tpo_connect
            - darkmatter
            - tazworks
            - internal
            - simplenexus
            - external_webpage
            - individual
            - alkami
            - blue_sage
            - lodasoft
            - blend
            - tidalwave
            - self_signup
        notification_settings:
          description: Configuration for order notifications
          type: object
          properties:
            suppress_user_notifications:
              description: >-
                When true, suppresses all user-facing notifications for this
                order. If enabled, first_notification_delay_hours is ignored.
              type: boolean
              default: false
              example: false
            first_notification_delay_hours:
              description: >-
                Number of hours to delay the first notification. Default is 0
                (immediate). Ignored when suppress_user_notifications is true.
              type: integer
              default: 0
              example: 0
              minimum: 0
        locale:
          description: Locale parameter (ISO 639) for regional customization of the order
          type: string
          enum:
            - en
            - ar
            - cmn
            - es
            - fa
            - hy
            - km
            - zh
            - hi
            - hmn
            - ja
            - ko
            - lo
            - ium
            - pa
            - pt
            - ru
            - so
            - tl
            - th
            - uk
            - vi
          example: es
    OrderBatchResult:
      type: object
      properties:
        index:
          type: integer
          description: Zero-based position of the order in the request.
          example: 0
        status:
          type: string
          description: >-
            `created` for a new order, `existing` when an order with the same
            `order_number` already existed, `failed` when the order could not be
            created.
          enum:
            - created
            - existing
            - failed
          example: created
        order_id:
          type: string
          nullable: true
          maxLength: 32
          description: ID of the created or existing order. Absent when the order failed.
          example: 39aa1486ccca4bc19cda071ffc1ba392
        order_number:
          type: string
          nullable: true
          maxLength: 512
          description: Your identifier for the order, if one was sent.
          example: CASE-001
        bridge_token:
          type: string
          nullable: true
          maxLength: 32
          description: Bridge token of the order.
          example: e4100fccdae94691b4414c7306220c06
        share_url:
          type: string
          nullable: true
          maxLength: 512
          description: Verification link to share with the applicant.
          example: >-
            https://cdn.truv.com/employment.html?bridge_token=e4100fccdae94691b4414c7306220c06
        short_share_url:
          type: string
          nullable: true
          maxLength: 512
          description: Shortened verification link to share with the applicant.
          example: https://truv.com/s/BIlEyh1A
        errors:
          type: object
          nullable: true
          description: >-
            Why this order could not be created, keyed by field. Set only when
            `status` is `failed`.
          example:
            last_name:
              - This field is required.
    EmployerCreate:
      type: object
      properties:
        start_date:
          description: Job start date
          type: string
          format: date
          example: '2019-08-24'
        end_date:
          description: Job end date
          type: string
          format: date
          example: '2019-11-27'
        company_name:
          description: Company name
          type: string
          example: Facebook Demo
          maxLength: 128
        company_address:
          description: Company address
          required:
            - street
            - city
            - state
            - zip
          type: object
          properties:
            street:
              description: >-
                Company location street. Returned exactly as provided when the
                order was created, and may contain multiple lines separated by
                `\n`.
              type: string
              example: 1 Hacker Way
              maxLength: 255
            city:
              description: >-
                Company location city. Returned exactly as provided when the
                order was created.
              type: string
              example: Menlo Park
              maxLength: 64
            state:
              description: >-
                Company location state. Typically a 2-letter state code;
                international region codes such as `NSW` are also accepted.
                Returned exactly as provided when the order was created.
              type: string
              example: CA
              maxLength: 32
            zip:
              description: >-
                Company location zip code. Typically a 5-digit US ZIP code;
                ZIP+4 and non-US postal codes also occur. Returned exactly as
                provided when the order was created.
              type: string
              example: '94025'
              maxLength: 10
        company_domain:
          description: Company website domain
          type: string
          example: facebook.com
          maxLength: 128
        company_logo:
          description: Company logo URL
          type: string
          format: uri
          example: https://cdn.truv.com/company_logos/facebook.svg
          maxLength: 512
        suborder_number:
          description: External ID
          type: string
          example: '133982343355'
          maxLength: 512
        account:
          description: >-
            Bank account info. Used for Direct deposit switching and Paycheck
            linked lending
          required:
            - account_number
            - routing_number
            - bank_name
          type: object
          properties:
            action:
              description: >

                Action to be performed on the account.


                `update` and `delete` actions are only available for the
                accounts that were previously created.
              type: string
              example: create
              enum:
                - create
                - update
                - delete
            account_number:
              description: >-
                Account number. Only digits are allowed, leading zeros will be
                preserved.
              type: string
              example: '16002600'
              maxLength: 20
              minLength: 4
            routing_number:
              description: >-
                Routing number. Only digits are allowed, leading zeros will be
                preserved.
              type: string
              example: '123456789'
              maxLength: 12
              minLength: 8
            account_type:
              description: |+

                Account type. Required for the `create` action.

                * `checking` - Checking account,
                * `savings` - Savings account

              type: string
              example: checking
              enum:
                - checking
                - savings
            bank_name:
              description: Bank name. Required for the `create` action.
              type: string
              example: TD Bank
              maxLength: 128
              minLength: 1
            bank_address:
              description: Bank address.
              type: string
              example: 123 Main St, New York, NY 10001
              maxLength: 1024
              minLength: 1
            deposit_type:
              description: >

                Deposit type.

                For `pll` product type is required and must be set to `amount`.

                For `deposit_switch` product type is optional and can be set to
                any supported value.


                * `entire` - Entire paycheck,

                * `percent` - Percentage of the paycheck,

                * `amount` - Fixed amount from the paycheck
              type: string
              example: entire
              enum:
                - entire
                - percent
                - amount
            deposit_value:
              description: >

                Deposit value.


                Possible values for this field depend on the `deposit_type`
                field:

                `percent` - this field must be set to a whole number between 0
                and 100.

                `amount` - this field must be set to a number between 0 and
                9999.99.

                `entire` - this field must be set to `null` or be not provided.
              type: string
              example: '50.00'
        company_mapping_id:
          description: Company mapping ID
          type: string
          example: self_employed
          maxLength: 64
        data_sources:
          description: >-
            List of data sources for the provided product_type. Leave blank to
            apply default values.
          type: array
          example:
            - payroll
          items:
            type: string
            enum:
              - payroll
              - docs
              - insurance
              - financial_accounts
              - tax
    FinancialInstitutionCreate:
      type: object
      properties:
        id:
          description: ID of a financial institution
          type: string
          maxLength: 64
        name:
          description: Name of a financial institution
          type: string
          example: Chase
          maxLength: 128
        suborder_number:
          description: External ID
          type: string
          example: '133982343355'
          maxLength: 512
    InsuranceCreate:
      type: object
      properties:
        provider_id:
          description: ID of a insurance provider
          type: string
          example: geico
      description: Insurance verification additional parameters
    Loan:
      type: object
      nullable: true
      anyOf:
        - required:
            - loan_number
        - required:
            - application_number
      properties:
        loan_number:
          description: Loan identifier
          type: string
          example: MUUT220700012
          maxLength: 128
          nullable: true
        application_number:
          description: Application (POS) file number
          type: string
          example: APP-2207-0001
          maxLength: 128
          nullable: true
        originator_name:
          description: Name of the loan originator
          type: string
          example: John Doe
          maxLength: 255
          nullable: true
        originator_email:
          description: Email of the loan originator
          type: string
          format: email
          example: john@example.com
          maxLength: 255
          nullable: true
        loan_processor_name:
          description: Name of the loan processor
          type: string
          example: John Doe
          maxLength: 255
          nullable: true
        loan_processor_email:
          description: Email of the loan processor
          type: string
          format: email
          example: john@doe.com
          maxLength: 255
          nullable: true
        external_id:
          description: External loan ID
          type: string
          nullable: true
          example: c505e0f1b4134fdc853fc87e7d2cc4a5
      description: Loan Information
    CreateReports:
      type: object
      properties:
        voa:
          $ref: '#/components/schemas/CreateVoaRequest'
        income_insights:
          $ref: '#/components/schemas/CreateIncomeInsightsRequest'
      description: Reports parameters
    CreateVoaRequest:
      type: object
      properties:
        days_requested:
          description: >-
            The specific duration in days for which the report is requested to
            be generated.
          type: integer
          maximum: 730
          minimum: 30
        as_of_date:
          description: >-
            The end date for the report period. Start date will be calculated as
            as_of_date - days_requested. Defaults to current date if not
            provided.
          type: string
          format: date
          example: '2024-12-31'
        large_deposit_threshold:
          type: object
          properties:
            fixed_amount:
              description: >-
                Amount that must be met or exceeded for deposits to be marked as
                large, when OTHER loan type is specified.
              type: integer
              maximum: 100000
              minimum: 0
            sales_price:
              description: >-
                Amount that must be met or exceeded for deposits to be marked as
                large, when FHA loan type is specified.
              type: number
              maximum: 1000000
              minimum: 10
            qualifying_monthly_income:
              description: >-
                Amount that must be met or exceeded for deposits to be marked as
                large, when CONVENTIONAL loan type is specified.
              type: number
              maximum: 100000
              minimum: 10
            loan_type:
              description: Loan type.
              type: string
              example: FHA
              enum:
                - FHA
                - CONVENTIONAL
                - OTHER
        is_voe:
          description: >-
            A boolean parameter to request a deposit based Verification of
            Employment report.
          type: boolean
        request_extended_history:
          description: >-
            A boolean parameter to enable extended transaction/statement
            history. Need to be set for days_requested more than 60 days
          type: boolean
      description: Verification of Assets report parameters
    CreateIncomeInsightsRequest:
      required:
        - days_requested
      type: object
      properties:
        days_requested:
          description: >-
            The specific duration in days for which the report is requested to
            be generated.
          type: integer
          maximum: 730
          minimum: 30
        consumer_report_permissible_purpose:
          description: >-
            Describes the reason you are generating an Income Insights Report
            for this user.
          type: string
          example: ACCOUNT_REVIEW_CREDIT
          enum:
            - ACCOUNT_REVIEW_CREDIT
            - ACCOUNT_REVIEW_NON_CREDIT
            - EMPLOYMENT
            - EXTENSION_OF_CREDIT
            - LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING
            - LEGITIMATE_BUSINESS_NEED_OTHER
            - WRITTEN_INSTRUCTION_PREQUALIFICATION
            - WRITTEN_INSTRUCTION_OTHER
      description: Income Insights report parameters.
  securitySchemes:
    ClientID:
      type: apiKey
      description: Client ID
      name: X-Access-Client-Id
      in: header
    AccessKey:
      type: apiKey
      description: Client Access Key
      name: X-Access-Secret
      in: header

````