---
title: "Create orders as a batch"
method: POST
path: "/v1/orders/batch/"
tags: ["Orders"]
---

# Create orders as a batch

`POST /v1/orders/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).

## Request body

- OrderBatch
  - `orders` Order[], required — Orders to create. Each item takes the same fields as a single order, and is validated individually when the batch runs.
    - `products` string[], required — Types of products selected for the order
    - `first_name` string, required — First name
    - `last_name` string, required — Last name
    - `ssn` string — 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.
    - `email` string, email — Subject's email
    - `phone` string — Subject's phone number. A 10-digit US number; accepted formats are normalized and stored as E.164 (`+14155554193`).
    - `order_number` string — External ID for the order.
    - `external_user_id` string, nullable — External user identifier. If not provided, order_number will be used for backwards compatibility.
    - `employers` EmployerCreate[] — List of employers
      - `start_date` string, date — Job start date
      - `end_date` string, date — Job end date
      - `company_name` string — Company name
      - `company_address` object — Company address
        - `street` string, required — Company location street. Returned exactly as provided when the order was created, and may contain multiple lines separated by `\n`.
        - `city` string, required — Company location city. Returned exactly as provided when the order was created.
        - `state` string, required — 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.
        - `zip` string, required — 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.
      - `company_domain` string — Company website domain
      - `company_logo` string, uri — Company logo URL
      - `suborder_number` string — External ID
      - `account` object — Bank account info. Used for Direct deposit switching and Paycheck linked lending
        - `action` 'create' | 'update' | 'delete' — Action to be performed on the account. `update` and `delete` actions are only available for the accounts that were previously created.
        - `account_number` string, required — Account number. Only digits are allowed, leading zeros will be preserved.
        - `routing_number` string, required — Routing number. Only digits are allowed, leading zeros will be preserved.
        - `account_type` 'checking' | 'savings' — Account type. Required for the `create` action. * `checking` - Checking account, * `savings` - Savings account
        - `bank_name` string, required — Bank name. Required for the `create` action.
        - `bank_address` string — Bank address.
        - `deposit_type` 'entire' | 'percent' | 'amount' — 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
        - `deposit_value` string — 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.
      - `company_mapping_id` string — Company mapping ID
      - `data_sources` string[] — List of data sources for the provided product_type. Leave blank to apply default values.
    - `financial_institutions` FinancialInstitutionCreate[] — List of financial institutions
      - `id` string — ID of a financial institution
      - `name` string — Name of a financial institution
      - `suborder_number` string — External ID
    - `insurance` InsuranceCreate — Insurance verification additional parameters
      - `provider_id` string — ID of a insurance provider
    - `manager` object — Associate your order manager info with an order.
      - `email` string, required — Email of the order manager
      - `name` string — Name of the order manager
    - `loan` union — Loan Information
      - object
        - `loan_number` string, nullable, required — Loan identifier
        - `application_number` string, nullable — Application (POS) file number
        - `originator_name` string, nullable — Name of the loan originator
        - `originator_email` string, email, nullable — Email of the loan originator
        - `loan_processor_name` string, nullable — Name of the loan processor
        - `loan_processor_email` string, email, nullable — Email of the loan processor
        - `external_id` string, nullable — External loan ID
      - object
        - `loan_number` string, nullable — Loan identifier
        - `application_number` string, nullable, required — Application (POS) file number
        - `originator_name` string, nullable — Name of the loan originator
        - `originator_email` string, email, nullable — Email of the loan originator
        - `loan_processor_name` string, nullable — Name of the loan processor
        - `loan_processor_email` string, email, nullable — Email of the loan processor
        - `external_id` string, nullable — External loan ID
    - `reports` CreateReports — Reports parameters
      - `voa` CreateVoaRequest — Verification of Assets report parameters
        - `days_requested` integer — The specific duration in days for which the report is requested to be generated.
        - `as_of_date` string, date — 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.
        - `large_deposit_threshold` object
          - `fixed_amount` integer — Amount that must be met or exceeded for deposits to be marked as large, when OTHER loan type is specified.
          - `sales_price` number — Amount that must be met or exceeded for deposits to be marked as large, when FHA loan type is specified.
          - `qualifying_monthly_income` number — Amount that must be met or exceeded for deposits to be marked as large, when CONVENTIONAL loan type is specified.
          - `loan_type` 'FHA' | 'CONVENTIONAL' | 'OTHER' — Loan type.
        - `is_voe` boolean — A boolean parameter to request a deposit based Verification of Employment report.
        - `request_extended_history` boolean — A boolean parameter to enable extended transaction/statement history. Need to be set for days_requested more than 60 days
      - `income_insights` CreateIncomeInsightsRequest — Income Insights report parameters.
        - `days_requested` integer, required — The specific duration in days for which the report is requested to be generated.
        - `consumer_report_permissible_purpose` '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' — Describes the reason you are generating an Income Insights Report for this user.
    - `template_id` string — ID of the template
    - `custom_field` string — Client provided custom field. Must be enabled in the dashboard customization section.
    - `cc_emails` string[] — A list of email addresses that will receive carbon copies (CC) of order status updates.
    - `notes` string, nullable — Free text field for notes associated with the order
    - `source` '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' — Type of the platform (internal, accio, etc.)
    - `notification_settings` object — Configuration for order notifications
      - `suppress_user_notifications` boolean — When true, suppresses all user-facing notifications for this order. If enabled, first_notification_delay_hours is ignored.
      - `first_notification_delay_hours` integer — Number of hours to delay the first notification. Default is 0 (immediate). Ignored when suppress_user_notifications is true.
    - `locale` 'en' | 'ar' | 'cmn' | 'es' | 'fa' | 'hy' | 'km' | 'zh' | 'hi' | 'hmn' | 'ja' | 'ko' | 'lo' | 'ium' | 'pa' | 'pt' | 'ru' | 'so' | 'tl' | 'th' | 'uk' | 'vi' — Locale parameter (ISO 639) for regional customization of the order
  - `template_id` string, nullable — Template applied to every order that does not set its own `template_id`.
  - `source` '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', nullable — Source applied to every order that does not set its own `source`.

## Response `202`

- OrderBatchJob
  - `id` string — Batch job ID. Use it to poll the job status.
  - `status` 'pending' | 'completed' | 'failed' — `pending` while orders are still being created, then `completed` once every order has an outcome, or `failed` if the whole job could not run.
  - `order_count` integer — Number of orders submitted in the request.
  - `created_count` integer — Number of orders that are usable, counting both `created` and `existing`.
  - `failed_count` integer — Number of orders that could not be created.
  - `results` OrderBatchResult[] — Outcome of each submitted order, matched to its position in the request.
    - `index` integer — Zero-based position of the order in the request.
    - `status` 'created' | 'existing' | 'failed' — `created` for a new order, `existing` when an order with the same `order_number` already existed, `failed` when the order could not be created.
    - `order_id` string, nullable — ID of the created or existing order. Absent when the order failed.
    - `order_number` string, nullable — Your identifier for the order, if one was sent.
    - `bridge_token` string, nullable — Bridge token of the order.
    - `share_url` string, nullable — Verification link to share with the applicant.
    - `short_share_url` string, nullable — Shortened verification link to share with the applicant.
    - `errors` object, nullable — Why this order could not be created, keyed by field. Set only when `status` is `failed`.
  - `errors` object[], nullable — 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.
    - `detail` string[] — Messages describing the failure.
  - `created_at` string, date-time — Time the batch was accepted.
  - `updated_at` string, date-time — Time the batch was last updated.

## Other responses

- `400` — HTTP 400 Bad Request
- `401` — HTTP 401 Unauthorized
- `403` — HTTP 403 Forbidden

---

[API](https://skmtc.net/truv/apis/truv-api.md) · [All operations](https://skmtc.net/truv/apis/truv-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/truv/truv-api/revisions/16345eb80970/schema)