Skip to main content

​
Getting Started with Finosu

This guide walks you through a typical workflow for using the Finosu API to manage customers and schedule automated calls.

​
The Standard Workflow

​
Step 1: Create a Customer

First, you’ll need to create a customer in the system. This represents the person you want to contact.

Create Customer

Add a new customer to your account
 Example Request: 
POST /customers
{
  "id": "customer-123",
  "name": "John Doe",
  "phoneNumber": "+15551234567",
  "timezone": "America/New_York"
}

​
Step 2: Create Scheduled Calls

Once you have a customer, create scheduled calls based on your desired schedule type (verification, collections, or custom).

Create Scheduled Calls

Schedule automated calls for your customer
 Example Request: 
POST /scheduled-calls/{customerId}
{
  "scheduleType": "collections"
}
This will return an array of scheduled calls with their scheduled times and statuses.

​
Step 3: Monitor Call Results

After calls are executed, you have two options to access the call data:

​
Option A: Fetch Calls via API

You can retrieve call information by querying the API directly:

Get Call by ID

Retrieve a specific call’s details

Get Calls by Customer

Retrieve all calls for a customer
Example Request: 
GET /calls/{id}

​
Option B: Receive Calls via Webhook

Configure a webhook to receive call data automatically when calls complete. This is the recommended approach for real-time processing.

Call Webhook

Receive automatic notifications when calls complete
 Webhook Payload: 
{
  "customerId": "customer-123",
  "transcript": "Agent: Hello, this is calling regarding your account. Is this John?\nCustomer: Yes, speaking.\nAgent: I'm calling to discuss your payment. We can help you set up a payment plan.\nCustomer: I already made a payment yesterday.\nAgent: Let me verify that for you...",
  "recording_url": "https://recordings.finosu.com/calls/abc123.mp3",
  "timestamp": "2025-10-21T10:30:00Z",
  "postProcessingFlags": [
    "CONNECT",
    "LIVE_CONNECT",
    "RPC",
    "CIP_PASSED"
  ]
}

​
Understanding Call Data

When you receive call data (either via API or webhook), it includes:
  • Transcript: Full conversation text
  • Recording URL: Link to the call audio
  • Post-Processing Flags: Automated flags indicating what happened during the call

​
Common Post-Processing Flags

The system automatically analyzes calls and sets flags such as:
  • DNC - Customer requested do not call
  • RPC - Right Party Contact (verified borrower)
  • VOICEMAIL_LEFT_MESSAGE - Message left on voicemail
  • COMPLAINT - Customer expressed complaint
  • DECEASED - Person reported as deceased
  • BANKRUPTCY - Customer mentioned bankruptcy

Get Scheduled Calls

View all scheduled calls and their post-processing flags

​
Managing Scheduled Calls

You can also manage scheduled calls after creation:

Cancel Single Call

Cancel a specific scheduled call

Cancel All Calls

Cancel all scheduled calls for a customer

​
Best Practices

  1. Use Webhooks for Real-Time Processing: Set up webhooks rather than polling the API for better performance and immediate notifications.
  2. Use Your Own Customer IDs: When creating customers, use the id field to pass your internal customer ID. This ensures you can easily reference customers between your system and Finosu.
  3. Monitor Post-Processing Flags: These flags provide valuable insights into customer interactions and compliance requirements.
  4. Handle DNC Flags: When you receive a DNC flag, make sure to update your systems to respect the customer’s request.
  5. Cancel Calls When Needed: If a customer makes a payment or resolves their issue, cancel pending scheduled calls to avoid unnecessary contact.