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 Customer Schedule Sync behavior. Enrollment does not cancel other calls, emails, or SMS. Conflicting applications, paused schedules, or other active call schedules return 409 for review. This guide covers enrollment only. For the shared request/response schema and API playground, see Customer Schedule Sync. 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.

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	Spreadsheet column	Enrollment requirement
`scheduleMode`	—	Required: `"enroll"`
`taskType`	Selected upload/cadence type	Required: `PendingLoanNewLead` or `PendingLoanReturning`, when enabled for your company
`id`	`ReferenceNumber`	Required customer reference
`loanId`	`ref_loan_id`	Required application reference
`firstName`	`FirstName`	Required
`lastName`	`LastName`	Required
`birthday`	`DOB`	Required date in the past; convert spreadsheet dates to `YYYY-MM-DD`
`ssnLastFour`	`SSN`	Required; exactly four digits
`phoneNumber`	`HomePhone`	At least one of `phoneNumber` and `mobilePhone` is required
`mobilePhone`	`MobilePhone`	Optional second number, or the only number when `phoneNumber` is absent
`middleName`	`MiddleName`	Optional
`streetAddress1`	`Address`	Optional
`streetAddress2`	—	Optional
`city`	`City`	Optional
`state`	`State`	Optional two-letter uppercase code
`zipCode`	`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`	`Email`	Optional valid email
`daysInApplied`	`days_in_applied`	Optional integer from 0 to 36,500; new leads only
`daysSincePaidOff`	`DaysSincePaidOff`	Optional integer from 0 to 36,500; returning borrowers only
`oneOff`	Selected one-off upload type	Optional boolean; returning borrowers only; default `false`
`isTest`	—	Optional boolean; default `false`; must match an existing customer’s test setting
`test`	—	Deprecated, removed on 25 October 2026 — send `isTest`. Still accepted and still honored

Omit optional values you do not have. Optional contact fields and the two cadence-age fields accept null; oneOff, test, isTest, and sync do not. Send the age fields as JSON integers, not strings, fractions, or booleans. Unrecognized fields are rejected rather than ignored. test and isTest mean the same thing and either is honored until the removal date. Sending both with different values is rejected with 422 and code conflicting_test_flags; nothing is enrolled. Because this endpoint rejects unrecognized fields outright, there is no risk of a payload quietly enrolling as production after the removal date — it will fail loudly. See the sync and enrollment window. 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. A finished, cancelled, or paused application cadence cannot be restarted by changing the idempotency key. Coordinate an intentional restart with your account manager; this enrollment operation does not provide it. Use Update 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 Get 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`	Conflicting application, contact restriction, finished/paused cadence, 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

Endpoint Examples

Enroll an Application

Supported task types

Example

Fields

Cadences

Retries

Response

Errors

​Supported task types

​Example

​Fields

​Cadences

​Retries

​Response

​Errors

Supported task types

Example

Fields

Cadences

Retries

Response

Errors