Skip to main content
Choose the business outcome you want to implement. Each workflow below explains what to submit, which references to keep, and how to check the result. For your first authenticated request, start with the Quickstart.

​
Choose your workflow

​
Enroll an application

Before you begin: confirm that the origination workflow is enabled for your company and use approved test records when validating the integration.
  1. Select a task type: PendingLoanNewLead or PendingLoanReturning.
  2. Enroll the application with scheduleMode: "enroll", the customer and application references, required fields, and a stable Idempotency-Key. Returning-borrower one-off outreach uses PendingLoanReturning with oneOff: true.
  3. Save the enrollment receipt. Follow its Location or use its scheduledCallId with Retrieve a Scheduled Call.
Verify success: HTTP 200 means the schedule was saved. Inspect the scheduled call’s status, then retrieve call results when available. Enrollment creates or reuses the customer; no separate customer-create or scheduled-calls request is required. Use the complete examples for the required payloads. For an uncertain submission, follow the enrollment endpoint’s idempotency rules; do not create a new key just to retry the same operation.

​
Enroll a list

Before you begin: prepare records for one company, preserving the customer and application references used in previous uploads.
  1. Send the list using Batch Enrollment with outer scheduleMode: "enroll", a stable header Idempotency-Key for the list, and a stable idempotencyKey for each enrollment row.
  2. Save the jobId and Location from the 202 Accepted response.
  3. Poll the returned location with the same company’s API key and reconcile every row using the batch status guide. Save successful enrollment receipts and inspect rejected rows individually.
Verify success: acceptance means the job was received, not that every application enrolled. Check per-row results and the resulting schedules. Follow the batch guide’s retry rules and documented limits.

​
Board a loan for collections

Before you begin: confirm that your account is configured for loan-based collections boarding. The collections task-type catalog returns supported names; it does not confirm account enablement.
  1. Create the customer, if not already present, with taskType: "Collections" and the required fields. Use your external customer reference consistently.
  2. Create the loan with the matching customerId, external loan id, taskType: "Collections", required loan fields, and servicingStatus: "ACTIVE" for a new loan.
  3. Retrieve the customer’s scheduled calls to inspect the resulting schedule, then monitor call results.
Verify success: check the customer and loan references in the responses and confirm the expected schedule for your configured workflow. Follow the loan endpoint’s contract when updating an existing record. See Upcoming API Changes for changes to the Create a Customer contract. Collections boarding is separate from origination enrollment.

​
Monitor Call Results

Choose the retrieval method that matches your integration: For company-wide history, persist the call id and follow nextCursor until it is null, keeping the company and filters consistent. The export example covers pagination and the endpoint’s retry behavior. For webhook delivery, use the call webhook contract and confirm the destination with your Finosu contact. Enrollment does not configure webhooks or write notes and flags to your loan management system. Verify success: reconcile received call references with your customer records. For webhooks, test a completed call against the agreed payload and your receiver.

​
Understanding Call Data

Each endpoint has its own response schema. Call detail exposes transcript, recordingUrl, and timestamp, which may be null; it does not expose flags or summaries. Company-wide call history uses a different schema and includes unsuccessful attempts and records still being processed. Scheduled-call responses describe scheduling state; their postProcessingFlags field is currently null. The call webhook is a separate object: it uses call_id, customer_id, to_phone_number, recording_url, and flags. Use call_id with Retrieve a Call. When present, loan_id is the external reference of the loan linked to that call’s schedule; it is not an internal loan UUID and may be omitted. Its timestamp describes preparation of the delivery attempt, while REST call detail’s timestamp is the call record’s creation time. Empty webhook flags are omitted; they are not the scheduled-call postProcessingFlags field. Use the webhook’s stable Idempotency-Key header for receiver-side deduplication and call_id for call correlation. A worker retry may refresh the delivery timestamp and recording URL, so do not use the body or timestamp as the deduplication key. See the webhook page for optional fields, recording-link expiry, and acknowledgment behavior.

​
Configure flag-based actions

  1. Retrieve public call flags for the selected taskType during integration setup.
  2. Use each entry’s name as the code and description as its explanation when configuring supported actions. Reuse the catalog according to the endpoint’s documented cache policy.
  3. Confirm how actual call flags arrive through your configured result delivery, then test the mapping with representative results.
Verify success: your integration recognizes the configured public codes and handles unrecognized codes without failing result processing. The catalog is a public subset shared across companies; it does not report flags from an individual call or enable workflows for your company. Call flags and stop-servicing reasons are separate catalogs. If an action stops servicing, choose a reason from the stop-servicing lookup. Do not assume a flag name is an accepted cancellation reason.

​
Managing Scheduled Calls

Inspect scheduled calls to follow scheduling state. Use Sync Customer Schedules replacement mode only when you intend to replace pending schedules. For origination intake, use scheduleMode: "enroll" as described above.

​
Stop calls or servicing

Choose the operation by its scope: For servicing cancellation, retrieve the accepted reasons and send the chosen case-sensitive value. Review the endpoint’s full effects, including scheduled payments, before selecting this operation. For funded applications or other origination stop events, follow Funded applications and stopping outreach. Keep the existing stop process until its replacement is validated. Cancelling pending calls does not prove that the parent cadence has stopped, and a new enrollment is not a cancellation signal.