Enroll an Application

Enroll an application in an automated origination call cadence by sending scheduleMode: "enroll" to the existing schedule-sync endpoint. Send one application per request here. For a whole list, use batch enrollment. The company associated with your X-API-Key determines which task types and cadences are available; contact your account manager to confirm the supported modes. Omitting scheduleMode, or setting it to "replace", retains the existing Sync Customer Schedules behavior. Enrollment does not cancel other calls, emails, or SMS. A different loanId creates a separate application for the same customer, even when an older application is still pending. Conflicts on the requested application and customer contact restrictions still return 409 for review. This guide covers enrollment only. For the shared request/response schema and API playground, see Sync Customer Schedules. For complete requests for each mode, see Origination Examples.

Supported task types

Origination enrollment (scheduleMode: "enroll") supports exactly two taskType values. Use the case-sensitive values shown below. Use List Task Types (GET /origination/task-types) to retrieve these values programmatically.

`taskType`	Purpose
`PendingLoanNewLead`	New application outreach: enrolls a new application in an automated outreach cadence.
`PendingLoanReturning`	Returning borrower outreach: enrolls a returning borrower in the configured outreach cadence.

The selected task type must be enabled for the company associated with your X-API-Key. A supported task type that is not enabled for your company returns 400. Contact your account manager to confirm availability. For a single returning-borrower call, use PendingLoanReturning with oneOff: true; this is an option, not a separate task type. See Cadences for scheduling behavior.

Example

curl --request POST 'https://api.finosu.com/customers/schedule/sync' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Idempotency-Key: application-1001-enrollment-1' \
  --header 'Content-Type: application/json' \
  --data '{
    "scheduleMode": "enroll",
    "id": "customer-1001",
    "loanId": "application-1001",
    "taskType": "PendingLoanNewLead",
    "firstName": "Jane",
    "lastName": "Doe",
    "birthday": "1985-06-15",
    "ssnLastFour": "1234",
    "phoneNumber": "+15125550100",
    "mobilePhone": "+15125550101",
    "zipCode": "78701",
    "timezone": "America/Chicago",
    "daysInApplied": 3
  }'

Successful enrollment saves the customer, application, and call schedule in one transaction. The normal scheduler starts outreach when calling hours, business-day rules, contact restrictions, and capacity allow. A successful API response means the schedule is saved; it does not mean a call has connected.

Returning customers and new applications

id identifies the customer in your account; loanId identifies the application. Keep the customer id stable when the same person applies again. Send the new application’s distinct loanId with a new Idempotency-Key and the required customer fields. This applies to both supported task types and batch enrollment. PendingLoanNewLead describes the outreach mode; it does not require a customer who has never existed in Finosu.

Request	Behavior
Same customer, new `loanId`	Creates a separate loan and cadence. Existing loans, outcomes, call history, and schedules remain intact, including pending or paused applications.
Same customer and `loanId`, matching active cadence with pending or in-progress calls	Returns `already_scheduled`; no duplicate calls or progress reset.
Same key and unchanged payload	Replays the original receipt; no new enrollment.
Same key with a different `loanId` or other changed data	Returns `409`; use a new key for a new application.
Same `loanId` assigned to another customer in your account	Returns `409`; references cannot be reassigned.
Same application with exhausted calls, both loan and application still `PENDING`, and a new key	Starts a complete new cadence in the same outreach mode, preserving application identity and previous history.
Terminal or unknown application/loan status, paused/cancelled cadence, contact restrictions, or inconsistent history	Returns `409`; no restart.

For example, customer customer-1001 can have application-1001 still pending and enroll application-1002 independently. Do not close the older application merely to enroll the new one. Report its actual final outcome separately through POST /originations/{id}/close, using that application’s reference. Loan reference ownership is scoped to the loan portfolio’s company. Loans explicitly marked as test loans do not reserve real application references and are excluded from the close API. An existing test loan on the same customer is never converted into a real application by submitting it again. The API customer test flag remains a separate setting with its existing validation. Customer data remains shared: creating a new application can update the existing customer’s supplied profile/contact fields through normal enrollment. It does not create another customer or remove contact restrictions. Each new cadence uses its own submitted call-plan inputs; older scheduled tasks are not rebuilt. Call eligibility and spacing continue to apply across the customer’s applications. Separate enrollment does not grant permission for simultaneous calls or bypass Do Not Call, calling hours, contact breaks, or capacity checks. A saved cadence is not a guarantee of immediate dialing. Completing all call attempts does not itself mark an application funded, withdrawn, or rejected.

Fields

Use strings for customer references, application references, ZIP codes, and SSN suffixes to preserve leading zeroes. Send birthdays as YYYY-MM-DD. Only the last four SSN digits are needed; do not send a full SSN.

API field	Enrollment requirement
`scheduleMode`	Required: `"enroll"`
`taskType`	Required: `PendingLoanNewLead` or `PendingLoanReturning`, when enabled for your company
`id`	Required customer reference
`loanId`	Required application reference
`firstName`	Required
`lastName`	Required
`birthday`	Required date in the past, formatted as `YYYY-MM-DD`
`ssnLastFour`	Required; exactly four digits
`phoneNumber`	At least one of `phoneNumber` and `mobilePhone` is required
`mobilePhone`	Optional second number, or the only number when `phoneNumber` is absent
`middleName`	Optional
`streetAddress1`	Optional
`streetAddress2`	Optional
`city`	Optional
`state`	Optional two-letter uppercase code
`zipCode`	Optional; used to derive the timezone when `timezone` is omitted
`timezone`	Required unless `zipCode` provides a known timezone; valid IANA timezone name only
`email`	Optional valid email
`daysInApplied`	Optional integer from 0 to 36,500; new leads only
`daysSincePaidOff`	Optional integer from 0 to 36,500; returning borrowers only
`oneOff`	Optional boolean; returning borrowers only; default `false`
`isTest`	Optional boolean; default `false`; must match an existing customer’s test setting

Omit optional values you do not have. Optional contact fields and the two cadence-age fields accept null; oneOff, isTest, and sync do not. Send the age fields as JSON integers, not strings, fractions, or booleans. Unrecognized fields are rejected rather than ignored. Both supplied phone numbers must have 10 digits, or 11 digits beginning with 1; the API normalizes them to +1…. This validates format, not whether a number is assigned or reachable. An invalid mobile number produces an error instead of silently changing the call plan. sync: true and nonempty externalMetadata are not supported in enrollment mode; send the explicit fields above. Enrollment preserves existing contact restrictions. It cannot remove a Do Not Call restriction through doNotCall: false; doNotCall: true is also rejected.

Cadences

Request	Result
`taskType: "PendingLoanNewLead"`	Nine calls over five business days, with phone rotation when two distinct numbers are provided. `daysInApplied` is recorded as context; it does not skip cadence steps.
`taskType: "PendingLoanReturning"` with `daysSincePaidOff`	Returning-borrower cadence based on days since payoff, with future calls through the configured horizon.
`taskType: "PendingLoanReturning"` without `daysSincePaidOff`	One initial call using the regular returning-borrower flow, which may include a mobile fallback.
`taskType: "PendingLoanReturning", oneOff: true`	Exactly one scheduled call, even with `daysSincePaidOff`; no mobile fallback.

A matching active cadence with a pending or in-progress call is returned as already_scheduled without changing borrower data or resetting its progress. The application reference, customer, company, and outreach mode must match; switching between returning and one-off is not an update to an existing cadence. For both New Lead and Returning Customer, a new idempotency key can restart fully exhausted outreach only when both the loan and captured application are still PENDING. Every previous call must be completed or failed, with no queued, claimed, active, cancelled, or compliance-suppressed work. Call post-processing must also be finished before a new cadence can start. Contact restrictions, paused/cancelled cadences, unknown state, and inconsistent identity block restart. FUNDED, WITHDRAWN, and REJECTED are never reopened, even if the other record still says PENDING. The restart creates a new schedule from step zero for the same application and outreach mode, preserving previous calls and receipts. Returning cadences with daysSincePaidOff start the complete configured cadence from the new start date; the supplied payoff-age information remains unchanged. Returning without that field and explicit oneOff retain their existing single-initial-call behavior. A retry using the original key always replays its original receipt, even after outreach has finished. CSV reuploads do not acquire this API restart behavior. Use Update a Customer for supported profile changes such as the primary phoneNumber, email, or timezone. That operation does not update mobilePhone, cadence-age fields, or oneOff, and it does not rebuild the call plan. Coordinate changes to those fields separately.

Retries

Idempotency-Key is required only for scheduleMode: "enroll". Use a stable, non-sensitive identifier of 1–128 characters: letters, digits, ., _, :, or -. Keep the same key and payload when retrying after a timeout or network error.

The same company, key, and normalized payload return the saved enrollment receipt, even after the cadence finishes or is cancelled.
Reusing a key with a different payload returns 409.
A different key for the same active application returns already_scheduled.
An in-progress request returns 409 with Retry-After; retry the original key.
Keys are scoped to the company associated with the API key.

Receipt replays still require a valid request, an enabled company/mode, and an available quota. They return the original scheduling result; they do not re-evaluate the current customer’s eligibility or start another cadence. Enrollment is limited to 60 requests per minute per company. Honor Retry-After on 429 and 503 responses and retry with exponential backoff and jitter.

Response

Responses use HTTP 200. The top-level customer fields are built from the normalized request, with two exceptions: phoneNumber falls back to mobilePhone when no primary number is supplied, and doNotCall is always returned as false. These fields are not a read of the current customer record. In particular, already_scheduled does not persist submitted contact changes, and doNotCall does not prove the customer is currently callable, including on a replay. Use Retrieve a Customer for the customer fields that operation exposes, and scheduled-call status for current scheduling state. Enrollment also returns mobilePhone, middleName, the schedule counters, and an origination receipt. Optional response fields can be null. The following is the scheduling portion of the response, not the complete customer response:

{
  "scheduleCreated": true,
  "tasksCreated": 9,
  "existingTasksRemoved": 0,
  "origination": {
    "id": "24ed9f67-d86f-450b-8d9a-0d67dbd89187",
    "status": "scheduled",
    "customerId": "customer-1001",
    "loanId": "application-1001",
    "scheduleId": "d514bcc6-b635-485e-a48a-695aec492c59",
    "scheduledCallId": "a584fa4a-c99d-4a84-ae43-39b119b3f152",
    "scheduledTime": "2026-09-21T16:00:00Z",
    "scheduledCallCount": 9
  }
}

Idempotency-Replayed: true identifies a replay. Its counters describe the original enrollment, not newly created calls. A newly submitted key returning already_scheduled has scheduleCreated: false and tasksCreated: 0. scheduledCallCount is the total number of nondeleted calls in the saved cadence, not the number of remaining attempts. Location points to /scheduled-calls/{scheduledCallId}. Use the scheduled call detail endpoint to track current status; the enrollment receipt is a snapshot.

Errors

Enrollment validation, conflict, and quota errors have a structured detail:

{
  "detail": {
    "code": "origination_conflict",
    "message": "Idempotency-Key was already used with a different request"
  }
}

Use detail.code to distinguish request_in_progress from other 409 conflicts. Authentication errors may instead contain a plain-string detail; do not assume every error has the enrollment shape. Invalid fields return sanitized messages without echoing the submitted identity values.

HTTP status	Meaning
`200`	Saved enrollment or existing cadence/receipt
`400`	Task type is not enabled for your company
`401`	Missing, empty, invalid, or inactive API key
`409`	Conflict on the requested application/reference, contact restriction, ineligible exhausted/paused cadence for that application, reused key with changed data, or request still in progress
`422`	Missing/invalid input or missing/invalid idempotency key
`429`	Per-company request quota exceeded
`503`	Scheduling temporarily unavailable; retry the same key and payload

API Documentation

Core Resources

Origination

Collections