Skip to main content
Send the list to POST /customers/batch with scheduleMode: "enroll". Finosu stores the upload, divides it into internal chunks, and enrolls each application using the same cadence and validation rules as individual enrollment. Your integration does not need to make one request per application. Use one company API key per list. That key selects the company and its configured portfolio; body fields cannot select a different company or enable another cadence.

Send a list

Use a stable Idempotency-Key header for the whole list and a stable idempotencyKey in each row for that enrollment operation. These are different keys with different purposes. Keep customer and application references consistent across API requests.
The example combines two modes. Each must be enabled for the authenticated company. Unsupported modes fail for the affected rows; they do not enable new portfolio capabilities. Returning borrowers without oneOff can include daysSincePaidOff for the existing returning cadence. Row fields follow the enrollment field contract, plus the required idempotencyKey. Row-level scheduleMode can be omitted; if present it must be "enroll". The outer scheduleMode is always required. Send isTest for test enrollments. An explicit null flag fails only the affected row. Omitting isTest defaults to false.
Always send the outer scheduleMode: "enroll". The existing customer-create workflow uses this URL without a mode. Enrollment row keys without the outer mode are rejected to prevent accidental customer-create processing.
See Batch API reference for the shared request schema and playground.

Acceptance and progress

A successful submission returns HTTP 202, Location, and a job ID:
Poll the Location URL with the same company’s API key. Start with a few seconds between polls and increase the interval for longer-running jobs.
The batch status endpoint returns:
  • status: pending, processing, completed, failed, or cancelled.
  • processed: successfully handled rows, including saved receipt replays and applications that were already scheduled.
  • failed: rejected rows or rows that exhausted processing retries.
  • progressPercentage: handled rows divided by the submitted count.
  • results: outcomes ordered by the original zero-based index. Each includes customerId, loanId, status, replayed, and retryable. Successful rows include the origination receipt; failures include code and message.
  • failures: the failed rows with their original index, customer reference, and message, for compatibility with existing batch clients.
Results appear as rows finish. A terminal completed job can have failed rows when at least one row succeeded; always inspect failed and results. A job with no successful rows ends as failed. A failure before the source can be read may have empty customer/application references; its original index still identifies the row in your submitted list. A saved schedule does not mean a call has connected. Use the receipt’s scheduledCallId to inspect the current call status. Receipts are scheduling snapshots, not current borrower eligibility.

Retry without duplicate enrollments

  • Submission timeout or 503: retry the identical ordered list with the same header key. If accepted previously, the same job is returned with Idempotency-Replayed: true. A changed list under that key returns 409. JSON object-key order is ignored; array order and submitted values must match.
  • Worker interruption: Finosu resumes processing and skips committed row results. Enrollment and its result are committed together.
  • Retryable failed row: submit that row in a new list with a new header key, retaining its original row idempotencyKey and payload. Replaying a terminal list returns the existing job; it does not restart failed rows.
  • Invalid row: correct the data and submit a new list. A rejected validation does not consume an enrollment receipt. If a key has already produced a saved receipt, changing its enrollment payload returns a conflict.
  • Contact or application conflict: review the reason before resubmitting. Enrollment cannot clear DNC, bypass a pause or reopen a terminal application.
  • Intentional restart: once all calls and their processing have finished, use a new list key and a new row key for the same application and outreach mode. Both the loan and captured application must still be PENDING. The restart rules apply to both New Lead and Returning Customer. Technical retries must retain their original keys.
Row keys share the individual enrollment key namespace within the company. A row submitted through batch and the single-record endpoint with the same key and normalized enrollment fields returns the same enrollment receipt. Use a separate row key for each distinct enrollment operation; do not reuse it for unrelated customers or applications.

Limits and processing behavior

  • Up to 10,000 records per request and 10 MiB of serialized customer data. Split larger lists into multiple batches with separate header keys.
  • Up to 10 batch submissions per minute per company, including submission retries. Honor Retry-After on 429 and 503.
  • Finosu processes internal chunks of 25 records in the background. The single-record endpoint’s 60-request/minute quota does not apply per batch row.
  • Rows and chunks can finish out of order. The list is not one transaction: valid rows can succeed while others fail. Do not depend on list order to apply multiple changes to the same customer.
  • Invalid envelopes return 422 before queuing. Oversized customer data returns 413. Invalid enrollment fields, disabled modes and application conflicts are reported per row after acceptance.
  • The normal scheduler still enforces contact restrictions, calling hours, phone rotation and the configured transfer routing. Batch intake does not change those settings or imply immediate calls.
Batch enrollment does not replace the funded/stop workflow or enable LMS notes and flags. See funded applications.

Multiple applications for one customer

Rows may share the same customer id when each represents a distinct loanId. Use a different row idempotencyKey for each application and preserve that key when retrying the same row. Enrollment creates separate loans and cadences without closing or retargeting older applications. Contact restrictions and call spacing remain customer-wide. See Returning customers and new applications.