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 writable via the public API is PAYMENT.
• 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.
amount	numeric string	Amount in the specified currency. Must be greater than 0.

{
  "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.

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.

{
  "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.