> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finosu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Workflows

> Learn the typical flow for using the Finosu API

## 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.

<Card title="Create Customer" icon="user-plus" href="/api-reference/endpoint/customers/create">
  Add a new customer to your account
</Card>

**Example Request:**

```json theme={null}
POST /customers
{
  "id": "customer-123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "+15551234567",
  "timezone": "America/New_York",
  "taskType": "Collections",
  "streetAddress1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001"
}
```

The required-field contract for this endpoint is changing — see [Upcoming API
Changes](/api-reference/upcoming-changes).

### Step 2: Create Scheduled Calls

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

<Card title="Create Scheduled Calls" icon="calendar-plus" href="/api-reference/endpoint/scheduled-calls/create">
  Schedule automated calls for your customer
</Card>

**Example Request:**

```json theme={null}
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:

<CardGroup cols={2}>
  <Card title="Get Call by ID" icon="phone" href="/api-reference/endpoint/calls/get-by-id">
    Retrieve a specific call's details
  </Card>

  <Card title="Get Calls by Customer" icon="list" href="/api-reference/endpoint/calls/get">
    Retrieve all calls for a customer
  </Card>
</CardGroup>

**Example Request:**

```json theme={null}
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.

<Card title="Call Webhook" icon="webhook" href="/api-reference/endpoint/calls/webhook">
  Receive automatic notifications when calls complete
</Card>

**Webhook Payload:**

```json theme={null}
{
  "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

<Card title="Get Scheduled Calls" icon="list-check" href="/api-reference/endpoint/scheduled-calls/get">
  View all scheduled calls and their post-processing flags
</Card>

## Managing Scheduled Calls

You can also manage scheduled calls after creation:

<CardGroup cols={2}>
  <Card title="Cancel Single Call" icon="ban" href="/api-reference/endpoint/scheduled-calls/cancel">
    Cancel a specific scheduled call
  </Card>

  <Card title="Cancel All Calls" icon="circle-xmark" href="/api-reference/endpoint/scheduled-calls/cancel-all">
    Cancel all scheduled calls for a customer
  </Card>
</CardGroup>

## 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.