Skip to main content
POST
/
api
/
v2
/
platform
/
spaces
/
{space_token}
/
tasks
/
create
Create a Task - Make Voice AI Call
curl --request POST \
  --url http://localhost:3001/api/v2/platform/spaces/{space_token}/tasks/create/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Org-Handle: <org-handle>' \
  --data '
{
  "phone_number": "+1234567890",
  "agent_handle": "sales-agent",
  "context": "Follow up on demo request"
}
'
{
  "status_code": 200,
  "message": "Task Created Successfully",
  "data": {
    "run_id": "R74802366fe9011f0878d43cd8a99e069",
    "task_ids": [
      "T74802367fe9011f0878d43cd8a99e069"
    ],
    "status": "pending"
  }
}

{
  "status_code": 200,
  "message": "Task Created Successfully",
  "data": {
    "run_id": "R74802366fe9011f0878d43cd8a99e069",
    "task_ids": [
      "T74802367fe9011f0878d43cd8a99e069"
    ],
    "status": "pending"
  }
}

​
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.

​
Path Parameters

NameTypeRequiredDescription
space_tokenstringYesPublic token of the space where task is created
You can get the space_token by hitting the Get All Spaces API. The token field in the response is your Space Token.

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Content-TypestringYesapplication/json

​
Request Body

FieldTypeRequiredDescription
pilotstringYesAgent/pilot handle to assign the task
documentsarrayYesArray of document/contact objects with data
contextstringNoAdditional context/objective for the task
scheduleobjectNoSchedule configuration (e.g., {"type": "now"})

​
Document Object Fields

FieldTypeRequiredDescription
namestringYesContact name
emailstringNoContact email address
contact_numberstringYesPrimary contact phone number
alternate_numberstringNoAlternate contact phone number
occupationstringNoContact’s occupation
company_namestringNoContact’s company name
addressstringNoContact’s address
aboutstringNoAdditional info about the contact
contextstringNoPer-contact context for the call
labelsarrayNoLabels/tags associated with the record
titlestringNoDocument title
descriptionstringNoDocument description
document_idstringNoUnique document identifier

​
Response Fields

FieldTypeDescription
status_codeintegerHTTP status code
messagestringResponse message
dataobjectCreated task details

​
Data Object Fields

FieldTypeDescription
run_idstringCreated run identifier
task_idsarrayArray of created task identifiers
statusstringTask status (initially pending)

​
Common Error Codes

Status CodeDescription
200Success - Task created successfully
206Partial Content - Business logic error occurred
400Bad Request - Invalid parameters provided
401Unauthorized - Invalid or missing API token
403Forbidden - Access denied to the resource
404Not Found - Space or Agent not found
500Internal Server Error - Server-side error

​
Code Examples

const axios = require('axios');

const headers = {
  'Authorization': 'Token your-api-token',
  'Content-Type': 'application/json'
};

// Create a task to make a Voice AI call
const createTask = async (spaceToken, pilot, documents, context) => {
  const response = await axios.post(
    `https://unpod.dev/api/v2/platform/spaces/${spaceToken}/tasks/create/`,
    {
      pilot,
      documents,
      context,
      schedule: { type: 'now' }
    },
    { headers }
  );
  console.log(`Run ID: ${response.data.data.run_id}`);
  console.log(`Task IDs: ${response.data.data.task_ids.join(', ')}`);
  return response.data.data;
};

// Example usage
createTask(
  '8KZAMRAHSXXXXXXMAYNASMJC',
  'space-agent-f1o3qjm1y7q1avvuynv4vprb1',
  [
    {
      name: 'John Doe',
      contact_number: '1234567890',
      email: 'john@example.com',
      context: 'Follow up on proposal'
    }
  ],
  'Call the lead and discuss the project requirements.'
);

​
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"

Path Parameters

​
space_token
string
required
Example:

"8KZRTQP7BNW5XEDLORYUHMJC"

Body

application/json
​
phone_number
string
required
Example:

"+1234567890"

​
agent_handle
string
required
Example:

"sales-agent"

​
context
string
Example:

"Follow up on demo request"

​
scheduled_at
string<date-time>
Example:

"2024-06-01T10:00:00Z"

Response

Task created successfully