canonical: https://jentic.com/apis/lula.com/gail

# Lula GAIL API

GAIL is Lula's AI-powered outbound calling platform, exposing a compact API for launching single and bulk outbound calls, building campaigns, attaching contacts, fetching call recordings, and retrieving CSV campaign reports. The 15 endpoints cover the core lifecycle: create a campaign, push contacts in, start or stop the campaign, and pull recordings or results out. Authentication is by X-API-Key header generated in the Gail Portal under General > Integrations > API Keys.

## For AI agents

Launch outbound AI voice calls one-off or in bulk, run campaigns over a contact list, and retrieve call recordings and CSV reports through Lula's GAIL platform.

## Scope

Does not handle SMS messaging, inbound IVR routing, or full conversation transcript management - use for outbound AI call placement, campaigns, contact attachment, and recording retrieval only.

## Capabilities

- Place a single outbound AI voice call to a phone number with a chosen script
- Launch a bulk batch of outbound calls in one request for high-volume outreach
- Create, start, stop, and update campaigns that drive calls against a contact list
- Add a single contact or bulk-add a contact list to an existing campaign
- Retrieve a pre-signed URL or download the audio file for a completed call recording
- Pull a CSV report of campaign results for downstream analytics

## Use cases

### AI-driven outbound dialling for sales and renewals

Sales and customer-success teams use GAIL to run AI-voiced outbound campaigns against a contact list - for example, calling a renewal cohort with a tailored script. POST /campaigns creates the campaign, POST `/campaigns/{id}/contacts/bulk_add` attaches the list, and POST `/campaigns/{id}/start` launches it. Reps then pull the CSV report from `/campaigns/{id}/report` once the campaign winds down.

Example prompt: Create a campaign named 'Q3 Renewals', bulk-add 250 contacts via POST `/campaigns/{id}/contacts/bulk_add`, and start it with POST `/campaigns/{id}/start.`

### Single ad-hoc outbound call from another workflow

When another system (CRM, helpdesk, internal tool) needs to trigger one outbound AI call rather than a campaign, POST /calls starts a single call with the chosen script and target number. The resulting callId can later be used with `/calls/{callId}/recording-url` to surface the audio in the originating tool.

Example prompt: Call POST /calls with the customer's phone number and the chosen script ID to launch a single outbound call, then poll `/calls/{callId}/recording-url` for the recording.

### Recording retrieval for QA and compliance

QA teams and compliance reviewers need access to the audio of completed AI calls. GET `/calls/{callId}/recording-url` returns a pre-signed URL good for short-lived access, or GET `/calls/{callId}/recording` streams the audio file directly. Pair with the campaign report endpoint to map recordings back to outcomes.

Example prompt: For callId abc-123, fetch GET `/calls/{callId}/recording-url` and return the pre-signed URL for the QA reviewer.

### Agent-driven campaign orchestration via Jentic

An AI sales agent needs to spin up a calling campaign in response to a Slack message ('renew the at-risk accounts this week') without writing custom GAIL integration code. Jentic stores the X-API-Key in your Jentic One instance and exposes the campaign create, contact add, start, and report endpoints by intent so the agent can chain them.

Example prompt: Search Jentic for 'create gail campaign', execute POST /campaigns, then chain bulk_add, start, and report operations against the new campaign ID.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/calls` | Start a single outbound call |
| POST | `/calls/bulk` | Start multiple outbound calls in bulk |
| GET | `/calls/{callId}/recording-url` | Get a pre-signed URL for a call recording |
| POST | `/campaigns` | Create a new campaign |
| POST | `/campaigns/{id}/start` | Start a campaign |
| POST | `/campaigns/{id}/contacts/bulk_add` | Bulk-add contacts to a campaign |
| GET | `/campaigns/{id}/report` | Download a CSV report of campaign results |

## Key resources

- **Calls** — Single and bulk outbound calls plus per-call recording access
- **Campaigns** — Create, list, update, start, stop campaigns and pull touchpoints and reports
- **Audio Files** — Catalogue of available audio assets for the calling platform
- **Call Recordings** — Pre-signed URLs and direct downloads for completed call audio

## Why Jentic

- **Setup:** Wiring the GAIL API by hand means sending the X-API-Key header on every call and threading one key across single and bulk call placement, campaign start, contact attachment, and recording retrieval. Through Jentic you install once, import the GAIL API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** GAIL puts the campaign id in the URL path (`/campaigns/{id}/...`), so a rule can pin your agent to one campaign: it can start that campaign, bulk-add its contacts, and read its report and nothing else. You choose the operations it may call, so single or bulk outbound call placement is not included unless you add it.
- **Credential handling:** Your GAIL key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start an outbound AI call', 'launch a calling campaign', or 'download a call recording', and Jentic returns the matching GAIL operation with its request schema so the agent calls the right endpoint directly.

## Related APIs

- **GAIL (Lula API)** — The full 103-endpoint Galactus surface for GAIL covering sequences, scripts, conversations, and webhooks
- **Bland.ai** — Competing AI voice agent platform for outbound and inbound calls
- **Retell AI** — Real-time AI voice agent platform for low-latency conversational calls

## FAQ

### What authentication does the GAIL API use?

GAIL uses an X-API-Key header. Generate the key in the Gail Portal under General > Integrations > API Keys and pass it as X-API-Key on every request to api.lula.com/v1. Through Jentic, the key is stored encrypted in your Jentic One instance and injected per call.

### Can I launch bulk outbound calls with the GAIL API?

Yes. POST `/calls/bulk` accepts a batch of outbound calls in a single request, which is more efficient than looping over POST /calls when running large campaigns. For long-running outreach, prefer the campaign endpoints (POST /campaigns followed by `/campaigns/{id}/contacts/bulk_add` and `/campaigns/{id}/start`) so GAIL handles pacing for you.

### What are the rate limits for the GAIL API?

Specific rate limits are not declared in the OpenAPI spec. Expect per-account caps tied to your Lula plan and outbound carrier capacity - design clients to retry on 429 responses and prefer bulk endpoints over tight loops on the single-call endpoint.

### How do I download a call recording through Jentic?

Search Jentic for 'gail call recording', load GET `/calls/{callId}/recording-url`, and execute it with the callId. Jentic returns the pre-signed URL with the X-API-Key applied; for the raw audio bytes, use GET `/calls/{callId}/recording` instead.

### Is the GAIL API the same as the larger GAIL (Lula API) v1 spec?

No - this 15-endpoint spec is the public v1 surface of GAIL. The companion spec lula.com/gail-api is a 103-endpoint Galactus External API covering the full platform, including conversations, sequences, scripts, do-not-call lists, webhooks, and sessions. Use this slimmer GAIL API when you only need calls, campaigns, contacts, and recordings.

### Can I limit what my agent is allowed to do with the GAIL API?

Yes. Because you self-host Jentic One, your own rules decide which GAIL operations and credentials the agent may use. Since GAIL puts the campaign id in the URL path (`/campaigns/{id}/...`), you can pin the agent to a single campaign so it can start that campaign, bulk-add its contacts, and read its CSV report and nothing else. Single and bulk outbound call placement stay excluded unless you explicitly grant those operations.