Connect Topcalls with Topcalls AI voice agents

Add Custom Carrier

Register a custom (BYOC) SIP carrier on your account for outbound calls.

Add Lead

Creates a lead and assigns it to a list.

Add Phone Number

Attaches a phone number to your account so it can place outbound calls. Body translation: phone_number→number, carrier_id→voip_carrier_sid.

Bulk Delete Leads by Filter

Deletes leads matching a filter (list, status, tag). The gateway runs sync (200) when the count is 500 or fewer, or async (202) with a job_id when larger. At least one filter field is required.

Bulk Delete Leads by IDs

Deletes a list of leads by UUID. Up to 500 ids per call, always sync. Returns counts plus a skipped payload for ids the gateway could not delete (not found, etc.).

Bulk Import Leads

Imports up to 2000 leads at once into a list. Payloads larger than 2000 leads are rejected by the gateway with a 400.

Cancel Queued Call

Cancels a call that is queued but has not started dialing yet.

Create Lead List

Creates a lead list, or returns the existing list if one already exists with the same name (case-insensitive match on trimmed name). Use the returned id with Add Lead or Bulk Import Leads.

Delete Lead

Deletes a lead by id. If list_id is supplied, removes only the lead-list assignment (lead itself stays).

Find Call by ID

Looks up a single call by its id and returns the full record.

Find Campaign by ID

Looks up a single campaign by its id. Returns null if not found.

Get Account Balance

Returns remaining call minutes and balance details for your account.

Get Feature Usage

Returns remaining call minutes plus a `features` array compatible with prior flows. Reads from /v1/balance.

List Campaigns

Returns the campaigns on your account. Result shape: { data: Campaign[], next_cursor: string | null }.

List Carriers

Returns the custom (BYOC) SIP carriers configured on your account, plus the default carrier id. Result shape: { carriers: AvailableCarrier[], default_voip_carrier_sid: string, count: number }. Loop over `carriers` to access individual carriers. The Topcalls system carrier is excluded, to use it, leave voip_carrier_sid blank when adding phone numbers.

List Phone Numbers

Returns the phone numbers attached to your Topcalls account. Result shape: { phone_numbers: PhoneNumber[], count: number }.

List Recent Calls

Returns recent calls, newest first. Result shape: { data: Call[], next_cursor: string | null }. Loop over `data` to access individual calls.

Make a Call

Starts an outbound AI phone call to the specified number.

Pause Campaign

Pauses a running campaign so the producer stops queuing new calls. In-flight calls are unaffected.

Remove Custom Carrier

Removes a custom (BYOC) SIP carrier from your account.

Remove Phone Number

Detaches a phone number from your account. The id is the internal phone-number record id (UUID), not the E.164 number.

Start Campaign

Activates a campaign so it begins dialing leads.

Stop In-Progress Call

Hangs up a call that is currently in progress.

Update Lead

Updates a lead by id. At least one optional field must be supplied. notes and notes_append are mutually exclusive: notes replaces, notes_append appends. Supplying both returns a gateway 400.