Quickstart - Finosu

Make a read-only request to verify your API key, then choose the integration workflow you want to build. This walkthrough does not create customers, loans, or outreach schedules.

Before you begin

You need curl and an active API key for your company. Obtain the key and confirm your integration environment with your Finosu contact. The requests below use https://api.finosu.com. Keep your API key on your server. Do not put it in browser code, shared examples, or source control.

1. Configure authentication

Set your key in the terminal where you will run the requests. Replace the placeholder with your company’s key:

export FINOSU_API_KEY='YOUR_API_KEY'

Finosu uses the X-API-Key header to authenticate requests and identify your company.

2. Retrieve a task-type catalog

Choose the catalog for your integration. Both requests are read-only.

Origination
Collections

Retrieve task types for new-lead and returning-borrower outreach:

curl --include \
  'https://api.finosu.com/origination/task-types' \
  --header "X-API-Key: ${FINOSU_API_KEY}"

Expected status: 200 OK. The JSON response body is:

["PendingLoanNewLead", "PendingLoanReturning"]

PendingLoanNewLead identifies new application outreach; PendingLoanReturning identifies returning-borrower outreach.

Retrieve the collections task type:

curl --include \
  'https://api.finosu.com/collections/task-types' \
  --header "X-API-Key: ${FINOSU_API_KEY}"

Expected status: 200 OK. The JSON response body is:

["Collections"]

Use Collections in the configured customer-and-loan boarding workflow.

A successful response confirms authentication. These catalogs are shared across companies and do not indicate which workflows your company has enabled. Treat the values as case-sensitive names, and read them by name rather than array position.

3. Choose your first business operation

Before submitting records, confirm the enabled workflow and approved test data with your Finosu contact. Write operations can create outreach schedules.

Workflow	Next step	How to verify the result
Origination	Follow the enrollment examples. Enrollment creates or reuses the customer; no separate customer-create request is required.	Save the enrollment receipt and inspect the returned scheduled-call reference. A saved schedule does not mean a call has completed.
Collections	Follow collections boarding: create the customer, then the loan for an account configured for loan-based boarding.	Inspect the customer’s scheduled calls and reconcile them with the submitted customer and loan.

For list imports, monitoring, and servicing changes, continue to Common Workflows.

If authentication fails

A missing, empty, invalid, or inactive API key returns 401 Unauthorized. Confirm that FINOSU_API_KEY is set in the same terminal, that the header name is X-API-Key, and that the key is active for the intended company and environment. If the response is still 401, contact Finosu to verify your credentials. For other operations, follow the endpoint’s documented error responses and request schema. Validation errors and retry behavior depend on the operation.

Concepts used in the guides

Concept	Meaning
Customer	The borrower record referenced by your integration.
Loan	A loan associated with a customer, with its own servicing state.
Task type	The workflow identifier, such as `PendingLoanNewLead` or `Collections`.
Cadence	The configured outreach sequence into which an application is enrolled.
Scheduled call	A scheduling record whose status you can inspect.
Call	A record of an executed call; available fields depend on the endpoint.

See call details for the response schema. Call detail does not expose flags or summaries; confirm those delivery contracts separately when configuring result delivery.

​Before you begin

​1. Configure authentication

​2. Retrieve a task-type catalog

​3. Choose your first business operation

​If authentication fails

​Concepts used in the guides