Phone

Use Phone endpoints for telephony resource management.

Authentication & scope

Header: X-API-Key: YOUR_API_KEY
Read operations: phone:read
Write operations: phone:write
Use API Reference for Try-it on each phone endpoint.

`GET /v1/phone/purchases`

Lists purchased numbers for your organization.

curl -X GET "https://api.indigenius.ai/v1/phone/purchases" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch('https://api.indigenius.ai/v1/phone/purchases', {
  headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
});
console.log(await response.json());

import requests
response = requests.get(
    "https://api.indigenius.ai/v1/phone/purchases",
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=30,
)
print(response.status_code)
print(response.json())

Common status codes

200 success
403 missing phone:read
500 server error

`GET /v1/phone/contacts/{id}`

Lists contacts for a purchased number.

curl -X GET "https://api.indigenius.ai/v1/phone/contacts/665e4a34c65bb95f2f2d72e4?page=1&pageSize=10" \
  -H "X-API-Key: YOUR_API_KEY"

const phonePurchaseId = '665e4a34c65bb95f2f2d72e4';
const response = await fetch(
  `https://api.indigenius.ai/v1/phone/contacts/${phonePurchaseId}?page=1&pageSize=10`,
  { headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY } },
);
console.log(await response.json());

import requests
phone_purchase_id = "665e4a34c65bb95f2f2d72e4"
response = requests.get(
    f"https://api.indigenius.ai/v1/phone/contacts/{phone_purchase_id}?page=1&pageSize=10",
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=30,
)
print(response.status_code)
print(response.json())

Common status codes

200 success
403 missing phone:read
404 purchase not found
500 server error

`POST /v1/phone/allocate-assistant`

Assigns inbound/outbound agents to a number. Body is DTO-accurate to PhoneAssistantDTO.

curl -X POST "https://api.indigenius.ai/v1/phone/allocate-assistant" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboundAssistantId": "665e4a34c65bb95f2f2d72e2",
    "outboundAssistantId": "665e4a34c65bb95f2f2d72e3",
    "id": "665e4a34c65bb95f2f2d72e4",
    "message": "Hello, this call may be recorded."
  }'

const response = await fetch(
  'https://api.indigenius.ai/v1/phone/allocate-assistant',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({
      inboundAssistantId: '665e4a34c65bb95f2f2d72e2',
      outboundAssistantId: '665e4a34c65bb95f2f2d72e3',
      id: '665e4a34c65bb95f2f2d72e4',
      message: 'Hello, this call may be recorded.',
    }),
  },
);
console.log(await response.json());

import requests
payload = {
    "inboundAssistantId": "665e4a34c65bb95f2f2d72e2",
    "outboundAssistantId": "665e4a34c65bb95f2f2d72e3",
    "id": "665e4a34c65bb95f2f2d72e4",
    "message": "Hello, this call may be recorded.",
}
response = requests.post(
    "https://api.indigenius.ai/v1/phone/allocate-assistant",
    headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
    timeout=30,
)
print(response.status_code)
print(response.json())

Common status codes

200 success
400 validation error
403 missing phone:write
404 resource not found
500 server error

`PATCH /v1/phone/{id}/call-forwarding`

Configures conditional call forwarding for a purchased number. Body is DTO-accurate to UpdateCallForwardingDTO.

always — every inbound call is forwarded immediately, without connecting to the assistant.
unavailable — forwarded only if the number has no inbound assistant assigned.
no_answer — forwarded if the assistant doesn’t pick up within the connect timeout.
busy — accepted by the API but not yet enforced.

Set callForwardingEnabled: false to turn forwarding off; callForwardingNumber and callForwardingWhen are then ignored.

curl -X PATCH "https://api.indigenius.ai/v1/phone/665e4a34c65bb95f2f2d72e4/call-forwarding" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callForwardingEnabled": true,
    "callForwardingNumber": "+14155559999",
    "callForwardingWhen": "unavailable"
  }'

const phonePurchaseId = '665e4a34c65bb95f2f2d72e4';
const response = await fetch(
  `https://api.indigenius.ai/v1/phone/${phonePurchaseId}/call-forwarding`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({
      callForwardingEnabled: true,
      callForwardingNumber: '+14155559999',
      callForwardingWhen: 'unavailable',
    }),
  },
);
console.log(await response.json());

import requests
phone_purchase_id = "665e4a34c65bb95f2f2d72e4"
payload = {
    "callForwardingEnabled": True,
    "callForwardingNumber": "+14155559999",
    "callForwardingWhen": "unavailable",
}
response = requests.patch(
    f"https://api.indigenius.ai/v1/phone/{phone_purchase_id}/call-forwarding",
    headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
    timeout=30,
)
print(response.status_code)
print(response.json())

Common status codes

200 success
400 validation error (e.g. callForwardingNumber missing or not E.164 when enabled)
403 missing phone:write
404 phone purchase not found
500 server error

`GET /v1/phone/{id}/call-forwarding/history`

Lists forwarding events for a purchased number, most recent first.

curl -X GET "https://api.indigenius.ai/v1/phone/665e4a34c65bb95f2f2d72e4/call-forwarding/history?page=1&pageSize=10" \
  -H "X-API-Key: YOUR_API_KEY"

const phonePurchaseId = '665e4a34c65bb95f2f2d72e4';
const response = await fetch(
  `https://api.indigenius.ai/v1/phone/${phonePurchaseId}/call-forwarding/history?page=1&pageSize=10`,
  { headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY } },
);
console.log(await response.json());

import requests
phone_purchase_id = "665e4a34c65bb95f2f2d72e4"
response = requests.get(
    f"https://api.indigenius.ai/v1/phone/{phone_purchase_id}/call-forwarding/history?page=1&pageSize=10",
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=30,
)
print(response.status_code)
print(response.json())

Common status codes

200 success
403 missing phone:read
404 phone purchase not found
500 server error

`POST /v1/phone/schedule-call`

Schedules outbound calls. Body is DTO-accurate to ScheduleCallDTO.

curl -X POST "https://api.indigenius.ai/v1/phone/schedule-call" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning outreach",
    "contacts_id": ["665e4a34c65bb95f2f2d72e5", "665e4a34c65bb95f2f2d72e6"],
    "phone_id": "665e4a34c65bb95f2f2d72e4",
    "message": "Hi, just checking in on your request.",
    "dates": ["2026-06-15T09:00:00.000Z"],
    "timezone": "GMT_plus_1"
  }'

const response = await fetch(
  'https://api.indigenius.ai/v1/phone/schedule-call',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({
      name: 'Morning outreach',
      contacts_id: ['665e4a34c65bb95f2f2d72e5', '665e4a34c65bb95f2f2d72e6'],
      phone_id: '665e4a34c65bb95f2f2d72e4',
      message: 'Hi, just checking in on your request.',
      dates: ['2026-06-15T09:00:00.000Z'],
      timezone: 'GMT_plus_1',
    }),
  },
);
console.log(await response.json());

import requests
payload = {
    "name": "Morning outreach",
    "contacts_id": ["665e4a34c65bb95f2f2d72e5", "665e4a34c65bb95f2f2d72e6"],
    "phone_id": "665e4a34c65bb95f2f2d72e4",
    "message": "Hi, just checking in on your request.",
    "dates": ["2026-06-15T09:00:00.000Z"],
    "timezone": "GMT_plus_1",
}
response = requests.post(
    "https://api.indigenius.ai/v1/phone/schedule-call",
    headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
    timeout=30,
)
print(response.status_code)
print(response.json())

`201 Created`

{
  "status": true,
  "message": "Call scheduled",
  "id": "665e4a34c65bb95f2f2d72e5"
}

Common status codes

201 scheduled
400 validation error
403 missing phone:write
404 resource not found
500 server error

`POST /v1/phone/contacts`

Adds a single contact to a purchased phone number. Body is DTO-accurate to ManualContactDTO.

curl -X POST "https://api.indigenius.ai/v1/phone/contacts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "665e4a34c65bb95f2f2d72e4",
    "name": "John Doe",
    "contact": "+14155552671"
  }'

const response = await fetch('https://api.indigenius.ai/v1/phone/contacts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.INDIGENIUS_API_KEY,
  },
  body: JSON.stringify({
    phone_id: '665e4a34c65bb95f2f2d72e4',
    name: 'John Doe',
    contact: '+14155552671',
  }),
});
console.log(await response.json());

import requests
payload = {
    "phone_id": "665e4a34c65bb95f2f2d72e4",
    "name": "John Doe",
    "contact": "+14155552671",
}
response = requests.post(
    "https://api.indigenius.ai/v1/phone/contacts",
    headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
    timeout=30,
)
print(response.status_code)
print(response.json())

Common status codes

200 success
400 validation error, or contact already exists
403 missing phone:write
404 phone number not found
500 server error

`POST /v1/phone/contacts/upload`

Uploads a contact list file (.xlsx, .vcf, or .csv) for a purchased phone number. Each phone number in the file must include a country code (start with +).

curl -X POST "https://api.indigenius.ai/v1/phone/contacts/upload" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "phone_id=665e4a34c65bb95f2f2d72e4" \
  -F "file=@contacts.csv"

const form = new FormData();
form.append('phone_id', '665e4a34c65bb95f2f2d72e4');
form.append('file', fileBlob, 'contacts.csv');

const response = await fetch(
  'https://api.indigenius.ai/v1/phone/contacts/upload',
  {
    method: 'POST',
    headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    body: form,
  },
);
console.log(await response.json());

import requests
files = {"file": open("contacts.csv", "rb")}
data = {"phone_id": "665e4a34c65bb95f2f2d72e4"}
response = requests.post(
    "https://api.indigenius.ai/v1/phone/contacts/upload",
    headers={"X-API-Key": "YOUR_API_KEY"},
    data=data,
    files=files,
    timeout=30,
)
print(response.status_code)
print(response.json())

`200 OK`

{
  "status": true,
  "message": "Contact list uploaded successfully. 42 contacts processed.",
  "data": {
    "totalProcessed": 42,
    "invalidContacts": 0
  }
}

Common status codes

200 success
400 unsupported file type, or numbers missing country code
403 missing phone:write
404 phone number not found
500 server error

`POST /v1/phone/announce`

Places an outbound announcer call: the system dials the destination number and, once the call connects, speaks a one-way message — either synthesized from text or played back from an audio source — using the voice configured on the assistant allocated to the purchased number, then automatically hangs up. The call never listens for or accepts caller audio; nothing the recipient says is transcribed or acted on. This is useful for reminders, alerts, one-time codes, or any broadcast-style message that doesn’t need a two-way conversation.

Provide exactly one of text, audioUrl, or the audioFile upload. Sending zero, or more than one, returns a 400.

How it’s routed

The underlying telephony carrier for the purchased number is resolved automatically — you don’t choose it.
The assistant used is the number’s outboundAssistantId if set, otherwise its inboundAssistantId. That assistant must be configured with a voice provider that supports announcer calls; assistants configured to rely on a full conversational voice engine are rejected, since announcer calls are one-way only (no conversation, no listening).
The call is placed first (a Calls record is created and the number is dialed), and once it connects, the announcement is streamed into the live call audio.
At the end of the call: the transcript, call analysis, and call tag are generated as with any other assistant call, and credit is deducted from your organization’s balance for call duration exactly as with /v1/calls/phone/initiate.

Request body

Field	Type	Required	Description
`phone_purchase_id`	string	yes	The purchased number to call out from.
`phoneNumber`	string	yes	Destination number, E.164 format.
`text`	string	one of `text` / `audioUrl` / `audioFile`	Text to synthesize and speak.
`audioUrl`	string (URL)	one of `text` / `audioUrl` / `audioFile`	Publicly reachable URL of an audio file to fetch and play.
`audioFile`	file	one of `text` / `audioUrl` / `audioFile`	Audio file upload (`multipart/form-data`). Accepted types: `mp3`, `mp4`/`m4a`, `wav`, `ogg`.

curl -X POST "https://api.indigenius.ai/v1/phone/announce" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "phone_purchase_id=665e4a34c65bb95f2f2d72e1" \
  -F "phoneNumber=+14155552671" \
  -F "text=Hello, this is a courtesy reminder about your appointment tomorrow at 10am."

curl -X POST "https://api.indigenius.ai/v1/phone/announce" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "phone_purchase_id=665e4a34c65bb95f2f2d72e1" \
  -F "phoneNumber=+14155552671" \
  -F "audioUrl=https://example.com/announcement.mp3"

curl -X POST "https://api.indigenius.ai/v1/phone/announce" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "phone_purchase_id=665e4a34c65bb95f2f2d72e1" \
  -F "phoneNumber=+14155552671" \
  -F "audioFile=@announcement.mp3"

const form = new FormData();
form.append('phone_purchase_id', '665e4a34c65bb95f2f2d72e1');
form.append('phoneNumber', '+14155552671');
form.append(
  'text',
  'Hello, this is a courtesy reminder about your appointment tomorrow at 10am.',
);

const response = await fetch('https://api.indigenius.ai/v1/phone/announce', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
  body: form,
});
console.log(await response.json());

const form = new FormData();
form.append('phone_purchase_id', '665e4a34c65bb95f2f2d72e1');
form.append('phoneNumber', '+14155552671');
form.append('audioFile', audioBlob, 'announcement.mp3');

const response = await fetch('https://api.indigenius.ai/v1/phone/announce', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
  body: form,
});
console.log(await response.json());

import requests
data = {
    "phone_purchase_id": "665e4a34c65bb95f2f2d72e1",
    "phoneNumber": "+14155552671",
    "text": "Hello, this is a courtesy reminder about your appointment tomorrow at 10am.",
}
response = requests.post(
    "https://api.indigenius.ai/v1/phone/announce",
    headers={"X-API-Key": "YOUR_API_KEY"},
    data=data,
    timeout=30,
)
print(response.status_code)
print(response.json())

import requests
data = {
    "phone_purchase_id": "665e4a34c65bb95f2f2d72e1",
    "phoneNumber": "+14155552671",
}
files = {"audioFile": open("announcement.mp3", "rb")}
response = requests.post(
    "https://api.indigenius.ai/v1/phone/announce",
    headers={"X-API-Key": "YOUR_API_KEY"},
    data=data,
    files=files,
    timeout=30,
)
print(response.status_code)
print(response.json())

`201 Created`

{
  "id": "665e4a34c65bb95f2f2d72e1",
  "type": "phone",
  "phone": "+14155552671",
  "callMode": "outbound",
  "status": 0
}

Use the returned id with the Calls endpoints — GET /v1/calls/{id}, GET /v1/calls/{id}/transcripts, GET /v1/calls/{id}/analysis, and GET /v1/calls/{id}/recording — to check on the announcement call afterwards.

Common status codes

201 announcer call initiated
400 validation error; zero or more than one of text/audioUrl/audioFile provided; the audio couldn’t be fetched or processed; the allocated assistant isn’t configured for announcer calls; the number’s carrier doesn’t support announcer calls; or the phone number is no longer active
403 missing phone:write
404 phone purchase or assistant not found
500 server error

Getting Started

Core APIs

Platform APIs

Phone

Phone

Authentication & scope

`GET /v1/phone/purchases`

Common status codes

`GET /v1/phone/contacts/{id}`

Common status codes

`POST /v1/phone/allocate-assistant`

Common status codes

`PATCH /v1/phone/{id}/call-forwarding`

Common status codes

`GET /v1/phone/{id}/call-forwarding/history`

Common status codes

`POST /v1/phone/schedule-call`

`201 Created`

Common status codes

`POST /v1/phone/contacts`

Common status codes

`POST /v1/phone/contacts/upload`

`200 OK`

Common status codes

`POST /v1/phone/announce`

How it’s routed

Request body

`201 Created`

Common status codes

​Phone

​Authentication & scope

​GET /v1/phone/purchases

​Common status codes

​GET /v1/phone/contacts/{id}

​Common status codes

​POST /v1/phone/allocate-assistant

​Common status codes

​PATCH /v1/phone/{id}/call-forwarding

​Common status codes

​GET /v1/phone/{id}/call-forwarding/history

​Common status codes

​POST /v1/phone/schedule-call

​201 Created

​Common status codes

​POST /v1/phone/contacts

​Common status codes

​POST /v1/phone/contacts/upload

​200 OK

​Common status codes

​POST /v1/phone/announce

​How it’s routed

​Request body

​201 Created

​Common status codes

Phone

Authentication & scope

`GET /v1/phone/purchases`

Common status codes

`GET /v1/phone/contacts/{id}`

Common status codes

`POST /v1/phone/allocate-assistant`

Common status codes

`PATCH /v1/phone/{id}/call-forwarding`

Common status codes

`GET /v1/phone/{id}/call-forwarding/history`

Common status codes

`POST /v1/phone/schedule-call`

`201 Created`

Common status codes

`POST /v1/phone/contacts`

Common status codes

`POST /v1/phone/contacts/upload`

`200 OK`

Common status codes

`POST /v1/phone/announce`

How it’s routed

Request body

`201 Created`

Common status codes