Create Task

Create a new task against a lead. The lead is identified by the :lead_id segment in the URL — use the lead's internal id (returned by Get Lead).

When you create a non-reminder task (FOLLOW_UP_CALL, FIRST_CALL, CALLBACK_REQUEST, SITE_VISIT, BOOKING), any other open non-reminder tasks on the same lead are automatically marked complete — only one non-reminder task is "open" at a time. Reminders are independent and don't get closed by creating other tasks.

Authentication Required

Requires the x-api-key header. See Overview for details.

HTTP Request

POST /enterprise/api/lead/:lead_id/task

Path Parameters

Parameter	Type	Required	Description
lead_id	number	Yes	Internal lead ID. Get this from Get Lead.

Request Body

Field	Type	Required	Description
type	string	Yes	Task type. One of FOLLOW_UP_CALL, FIRST_CALL, CALLBACK_REQUEST, SITE_VISIT, REMINDER, BOOKING.
due_date	string	Yes	When the task is due. ISO 8601 timestamp (e.g. 2026-05-20T15:00:00Z).
notify_at	string	No	When the assignee should be notified. ISO 8601 timestamp. Must satisfy now < notify_at <= due_date — in the future and at or before the due time. Defaults are derived from due_date and type: REMINDER notifies at due_date, FIRST_CALL notifies immediately, other types notify 10 minutes before due_date.
customer_note	string	No	A note to attach to this task. Visible on the lead timeline.

The task is created against the lead and inherits the lead's current assignee — there's no separate assignee field on this API.

Try it

Loading playground…

Code Examples

cURL

curl -X POST https://prod-api.superfone.co.in/superfone/enterprise/api/lead/12345/task \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FOLLOW_UP_CALL",
    "due_date": "2026-05-20T15:00:00Z",
    "customer_note": "Customer asked about volume discount."
  }'

JavaScript

const leadId = 12345;
const response = await fetch(
  `https://prod-api.superfone.co.in/superfone/enterprise/api/lead/${leadId}/task`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SF_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'FOLLOW_UP_CALL',
      due_date: '2026-05-20T15:00:00Z',
      customer_note: 'Customer asked about volume discount.'
    })
  }
);

const result = await response.json();
console.log(result.data);

Python

import os
import requests

lead_id = 12345
response = requests.post(
    f'https://prod-api.superfone.co.in/superfone/enterprise/api/lead/{lead_id}/task',
    headers={
        'x-api-key': os.environ['SF_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'type': 'FOLLOW_UP_CALL',
        'due_date': '2026-05-20T15:00:00Z',
        'customer_note': 'Customer asked about volume discount.'
    }
)
print(response.json()['data'])

Success Response

Status Code: 200 OK

{
  "data": {
    "id": 4567,
    "org_id": 42,
    "customer_id": 12345,
    "title": null,
    "type": "FOLLOW_UP_CALL",
    "type_name": null,
    "due_date": "2026-05-20T15:00:00.000Z",
    "notify_at": "2026-05-20T14:50:00.000Z",
    "notify": true,
    "task_status": "PENDING",
    "status": "ACTIVE",
    "assignee_user_id": 678,
    "created_by": 1,
    "updated_by": null,
    "created_at": "2026-05-19T08:30:00.000Z",
    "updated_at": "2026-05-19T08:30:00.000Z"
  },
  "message": "success"
}

Response Fields

Field	Type	Description
data.id	number	Internal task ID. Useful for correlating with the dashboard.
data.customer_id	number	The lead this task belongs to.
data.type	string	Task type.
data.task_status	string	PENDING for newly-created tasks.
data.due_date	string	ISO 8601.
data.notify_at	string	ISO 8601. When the notification was scheduled to fire.
data.assignee_user_id	number | null	Assigned team member.
data.created_at	string	ISO 8601.

Error Responses

Status	Message	When it occurs
400	lead_id must be a number	URL contains a non-numeric :lead_id
400	Request body is empty	The request body is missing or empty
400	type is required	type missing from body
400	type "<value>" is not available for creation. Allowed: ...	type is not in the allowed task-type list. The error response lists every currently-allowed value.
400	due_date is required	due_date missing from body
401	UnAuthorized, Please Provide Valid API Key	Missing or invalid x-api-key
404	Lead not found	lead_id doesn't exist, or belongs to a different account
404	Lead storage is full	Your account has reached its lead storage limit

Related Endpoints

• Complete Task — Mark the lead's currently-open task complete
• List Tasks — Paginated task history for a lead
• Get Lead — Look up a lead's id by phone