​
Custom Data Source Integration Guide

This guide explains, from your perspective as the data‐owner, exactly what you need to provide so that our Voice AI platform can fetch your records in real time—no CSV uploads needed. You will implement and expose a single “records” endpoint; when you create a list in our UI, you simply supply that endpoint URL (plus any parameters) and we’ll handle the rest.

​
1. Overview of the Workflow

1

Deploy Your Endpoint

You deploy an HTTP endpoint on your systems that, when called, returns your latest contact records in JSON.
2

Create List in Dashboard

In our Dashboard, you create a new List, giving:
  • A List Name & optional description
  • Your Records Endpoint URL (the URL we’ll call to fetch data)
  • Any static query parameters (e.g. API key in the URL, list-specific filters)
3

Real-time Fetching

At call-time, our Scheduler issues a GET to your endpoint with two query parameters:
  • since (ISO 8601 timestamp of the last fetch; optional on first run)
  • list_id (the identifier we assigned when you created the list)
4

Process Records

Your endpoint returns a JSON payload of records. We normalize and dial them.
5

Download Results

After the campaign, we generate a CSV of results you can download manually from our UI.

​
2. What You Need to Provide

​
2.1 Records Endpoint URL

When creating or editing a list, you will enter: 
https://api.yourcompany.com/voice-integration/v1/records
Any static parameters (like your API key) can live here as query strings.

​
2.2 Dynamic Query Parameters

Our platform will append at runtime:

list_id

The opaque ID we assign you (list_abc123)

since

An ISO 8601 timestamp marking the last time we fetched this list (e.g. 2025-06-12T00:00:00Z). On the first fetch, this will be omitted; return all active records.
Full example call: 
GET https://api.yourcompany.com/voice-integration/v1/records?
      list_id=list_abc123
      &since=2025-06-12T00:00:00Z

​
3. Records Payload Specification

Your endpoint must return 200 OK with a JSON body conforming to this schema: 
{
  "records": [
    {
      "id": "string",         // unique record identifier
      "phone": "string",      // E.164 formatted number, e.g. "+15551234567"
      // any additional fields you need our AI to know:
      "firstName": "string",
      "lastName": "string",
      "customFieldX": "string",
      …
    },
    …
  ]
}
  • records: an array, possibly empty.
  • Each record must include at least id and phone; other fields are optional metadata.
  • Empty result: return { "records": [] } if no new or matching records.

​
4. Pagination & Large Datasets

If your record set can be large, support pagination using either:
Query parameters: limit (max items) and offset (starting index).
GET /records?list_id=list_abc123&since=…&limit=1000&offset=0

​
5. Error Handling

​
Sample Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Missing required field 'phone' in record[5]",
  "details": [
    "records[5].phone is required"
  ]
}

​
6. Testing Your Integration

1

Implement & Deploy

Implement & deploy your /records endpoint.
2

Create List

Create a List in our Dashboard:
  • Enter List Name and your Records Endpoint URL.
3

Test Fetch

Trigger a manual fetch:
  • Use our “Test Fetch” button to simulate a call to your endpoint with list_id (and since empty).
4

Verify

Verify:
  • Inspect that our sample GET hits your service correctly.
  • Ensure your JSON response matches the schema and returns expected contacts.
5

Adjust

Adjust any query logic, filters, or pagination until the test fetch succeeds.

​
7. Go Live

Schedule

Once testing passes, schedule your list for regular dialing (e.g. every 15 minutes) via our UI.

Automatic Processing

Our system will automatically call your endpoint at each interval, fetch new records, and process them for calling.

Download Results

After each campaign, download the CSV of results from the “Results” tab.
With just one endpoint to build and a simple JSON contract to follow, you’ll be up and running in minutes—enabling real-time, automated dialing against your freshest data. If you have any questions or need assistance, our integration team is here to help!