Sign in
OpenAPI 3.0.12026-08-1591238712.0 KB

16345eb80970

Orders

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 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.

post/v1/orders/batch/

Request body

template_idstring 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.

Example request

{
  "orders": [
    {
      "products": [
        "income"
      ],
      "first_name": "John",
      "last_name": "Doe",
      "ssn": "222233333",
      "phone": "4155554193",
      "order_number": "1534332",
      "external_user_id": "user_12345",
      "employers": [
        {
          "start_date": "2019-08-24",
          "end_date": "2019-11-27",
          "company_name": "Facebook Demo",
          "company_address": {
            "street": "1 Hacker Way",
            "city": "Menlo Park",
            "state": "CA",
            "zip": "94025"
          },
          "company_domain": "facebook.com",
          "company_logo": "https://cdn.truv.com/company_logos/facebook.svg",
          "suborder_number": "133982343355",
          "account": {
            "action": "create",
            "account_number": "16002600",
            "routing_number": "123456789",
            "account_type": "checking",
            "bank_name": "TD Bank",
            "bank_address": "123 Main St, New York, NY 10001",
            "deposit_type": "entire",
            "deposit_value": "50.00"
          },
          "company_mapping_id": "self_employed",
          "data_sources": [
            "payroll"
          ]
        }
      ],
      "financial_institutions": [
        {
          "name": "Chase",
          "suborder_number": "133982343355"
        }
      ],
      "insurance": {
        "provider_id": "geico"
      },
      "manager": {
        "email": "john.doe@example.com",
        "name": "John Doe"
      },
      "loan": {
        "loan_number": "MUUT220700012",
        "application_number": "APP-2207-0001",
        "originator_name": "John Doe",
        "originator_email": "john@example.com",
        "loan_processor_name": "John Doe",
        "loan_processor_email": "john@doe.com",
        "external_id": "c505e0f1b4134fdc853fc87e7d2cc4a5"
      },
      "reports": {
        "voa": {
          "as_of_date": "2024-12-31",
          "large_deposit_threshold": {
            "loan_type": "FHA"
          }
        },
        "income_insights": {
          "consumer_report_permissible_purpose": "ACCOUNT_REVIEW_CREDIT"
        }
      },
      "template_id": "9b96606355b94e8abff8ed8d75aa2027",
      "notes": "To be processed by John Doe",
      "source": "floify",
      "locale": "es"
    }
  ],
  "template_id": "9b96606355b94e8abff8ed8d75aa2027",
  "source": "internal"
}

Response

idstring

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_countinteger

Number of orders submitted in the request.

created_countinteger

Number of orders that are usable, counting both created and existing.

failed_countinteger

Number of orders that could not be created.

created_atstring date-time

Time the batch was accepted.

updated_atstring date-time

Time the batch was last updated.

Example response

{
  "id": "9f2c1b7e4a3d4e8fa1b2c3d4e5f60718",
  "status": "completed",
  "order_count": 3,
  "created_count": 2,
  "failed_count": 1,
  "results": [
    {
      "status": "created",
      "order_id": "39aa1486ccca4bc19cda071ffc1ba392",
      "order_number": "CASE-001",
      "bridge_token": "e4100fccdae94691b4414c7306220c06",
      "share_url": "https://cdn.truv.com/employment.html?bridge_token=e4100fccdae94691b4414c7306220c06",
      "short_share_url": "https://truv.com/s/BIlEyh1A",
      "errors": {
        "last_name": [
          "This field is required."
        ]
      }
    }
  ],
  "errors": [
    {
      "detail": [
        "The batch could not be processed."
      ]
    }
  ],
  "created_at": "2026-08-10T09:14:22.881Z",
  "updated_at": "2026-08-10T09:15:04.203Z"
}