Actions

An action is an event recorded on a lead's timeline. Actions can be sent in the same payload that creates or updates a lead, or attached to existing leads later.

There are two kinds of actions:

• Predefined actions — built into telecrm. The only predefined action accepted in the actions payload is PAYMENT. ATTACHMENT actions are created through POST .../file.
• Custom actions — defined per workspace under Settings → Custom Actions.

Action payload shape

Actions are sent as an array on the actions key. Each entry is an object with at minimum a type, plus any fields the action requires.

{
  "fields": { "phone": "919999999999" },
  "actions": [
    { "type": "ACTION_1001", "fields": { "note": "Site visit completed" } },
    { "type": "PAYMENT", "status": "COMPLETED", "currency": "INR", "amount": "5000" }
  ]
}

Predefined: PAYMENT

A payment event on the lead. Every payment action requires the four fields below.

Field	Type	Notes
type	"PAYMENT" (literal)	Identifies the action as a payment.
status	enum	One of PENDING, COMPLETED, FAILED, REFUNDED, CANCELLED, PROCESSING.
currency	enum	One of INR, USD, PKR, AED, QAR, SAR, MYR, AUD, CAD, SGD, XOF, EUR, NPR, BHD.
amount	numeric string	Amount in the specified currency. Must be greater than 0.
employeeid	string (optional)	Email of the team member who recorded the payment. Defaults to the telecrm system user.

{
  "type": "PAYMENT",
  "status": "COMPLETED",
  "currency": "INR",
  "amount": "5000"
}

Custom actions

Custom actions are workspace-defined. Each has a unique numeric code (e.g. 1001) and a schema of fields configured in the dashboard.

Find a custom action's code

1. Go to Settings → Custom Actions.
2. Locate the action in the table.
3. Note its ID column — that's the numeric code.

The ACTION_ prefix (Async only)

The Async API requires the custom action's type to be the numeric code prefixed with ACTION_.

API	type format	Example
Async	ACTION_<code>	ACTION_1001
Sync	<code> (bare)	1001

WARNING

On the Async API, a custom action without the ACTION_ prefix is silently dropped. The lead may still be created or updated, but the action will not appear on the timeline.

Attributing an action

Actions created through the API are attributed to telecrm, the system user, unless the entry carries an employeeid holding a team member's email address:

{
  "type": "ACTION_1001",
  "employeeid": "agent@company.com",
  "fields": { "note": "Site visit completed" }
}

The email must belong to an active team member. An unresolvable email falls back to the system user — a custom action is still created and carries an IGNORED remark, while a PAYMENT entry is dropped. employeeid is a top-level key on the action, not a member of fields, and it cannot be changed once the action exists.

Backdating an action

A custom action entry may carry a top-level created_on alongside type and fields, setting the action's timestamp to a moment in the past instead of now.

{
  "type": "ACTION_1001",
  "created_on": "01/01/2026 09:30:00",
  "fields": { "note": "Logged late" }
}

• Accepts epoch milliseconds or a DD/MM/YYYY HH:mm:ss string.
• It is honoured only when the action definition has allowPredatedActivity: ALLOW. Otherwise the action is still created, at the current time, with the remark Can't set a previous date for this action type.
• Check a definition's setting with GET /custom-actions?detail=true.
• PAYMENT actions do not support created_on.

Custom action fields

The fields object on a custom action follows the exact same rules as lead fields — keys are field API names, values must match the workspace-defined field type.

FILE fields are the exception: they are ignored in fields. Set them after the action exists with POST .../action/{actionId}/file.

{
  "type": "ACTION_1001",
  "fields": {
    "note": "Site visit completed",
    "visit_date": "01/01/2023 10:30:00",
    "outcome": "Interested"
  }
}

See Field Types for the full input rules and Field API Names for how to find each field's API name.