Skip to main content
POST

Create a Task - Make Voice AI Call

Create a new task inside a given space using the space’s public token. You can assign the task to a pilot/agent, attach multiple documents (contacts), provide additional context, and schedule the execution.
Prerequisites: Make sure you have your API Token, Space Token, and Agent Handle ready. See Authentication for details.

Endpoint

Path Parameters

string
required
Public token of the space where the task is created.
Get this from the Get All Spaces API - use the token field.

Headers

string
required
API Key in format: Token <your-api-token>
string
required
Must be application/json

Request Body

string
required
Agent/pilot handle to assign the task to.
array
required
Array of document/contact objects. Each document represents one contact to call.
string
Additional context/objective for the task (applies to all contacts).
object
Schedule configuration. Example: {"type": "now"}

Response Fields

integer
HTTP status code
string
Response message
object
Created task details

Common Error Codes

Code Examples

Best Practices

  1. Pilot Handle: Use the correct agent handle from the Get All Agents API
  2. contact_number: Always include a valid contact_number in each document - this is required for call execution
  3. Batch Calls: Pass multiple documents in the documents array to trigger batch calls in a single request
  4. Context: Provide clear, specific context to guide the agent’s conversation objectives
  5. Run ID: Store the returned run_id to track task execution status using the Get All Runs API
  6. Security: Keep API tokens secure and rotate them regularly

Authorizations

Authorization
string
header
required

Format: Token

Headers

Org-Handle
string
required

Organization domain handle

Example:

"unpod.tv"

Path Parameters

space_token
string
required
Example:

"8KZAMRAHSXXXXXXMAYNASMJC"

Body

application/json
pilot
string
required

Agent/pilot handle to assign the task

Example:

"space-agent-f1o3qjm1y7q1avvuynv4vprb1"

documents
object[]
required

Array of contact/document objects

context
string

Additional context for the task

Example:

"Call the lead and discuss the project requirements."

schedule
object

Schedule configuration

Example:

Response

Task created successfully