Pitfalls ​

The Async API reports the lead-level outcome — Created or Updated — but nothing about individual fields. Fields and actions that fail validation are dropped without a word. The pitfalls below are the most common reasons a lead lands but its data doesn't.

Missing ACTION_ prefix on a custom action ​

Symptom. The lead is created or updated, but the custom action does not appear on the timeline.

Cause. On the Async API, custom action type values must be prefixed with ACTION_ followed by the numeric code. Bare numeric codes are valid only on the Sync API.

Fix. Prefix the code: "type": "1001" → "type": "ACTION_1001".

diff
  "actions": [
-   { "type": "1001", "fields": { "note": "..." } }
+   { "type": "ACTION_1001", "fields": { "note": "..." } }
  ]

See Actions → The ACTION_ prefix.

Missing the lead identifier ​

Symptom. No lead is created or updated for a request that returned 200.

Cause. The payload's fields object did not include the workspace's lead identifier (default: phone). The request is silently dropped.

Fix. Always include the identifier field. Confirm which field is the identifier under Settings → Lead Fields in the dashboard.

diff
  {
    "fields": {
      "name": "Jane Doe",
+     "phone": "919999999999"
    }
  }

Wrong field type for a value ​

Symptom. The field is missing on the resulting lead, even though the lead itself was created.

Cause. The value did not match the field's defined type. Examples:

  • Sending a string "3" for a rating field that expects an integer.
  • Sending a comma-separated string "VIP, Returning" for a tags field that expects an array.
  • Sending an unformatted phone like "99999" for a phone field with no country code.

Fix. Match the field type. See Field Types for input rules per type.

Date format mismatch ​

Symptom. A date field is empty, or stored as a wrong date.

Cause. The Async API accepts only two date formats: epoch milliseconds, or the workspace-configured date format string. ISO 8601 (e.g. "2026-01-01T10:30:00Z") is not parsed.

Fix. Use one of the two accepted formats. Find the workspace format under Settings → Lead Fields → click the date field → Properties → Date format.

diff
- "follow_up_date": "2026-01-01T10:30:00Z"
+ "follow_up_date": 1767262200000
+ "follow_up_date": "01/01/2026 10:30:00"

Treating 200 as confirmation that every field landed ​

Symptom. The response says "status": "Created" and gives a lead ID, but several fields are empty on the lead.

Cause. The response reports the lead-level outcome only. Each field is validated separately during processing, and a field that fails — wrong type, unknown API name, hidden in the workspace — is dropped with nothing said about it. Actions missing the ACTION_ prefix vanish the same way.

Fix. Read status and errorMessage for the lead-level result, then verify field-level ingestion through the dashboard, or read the lead back with GET /lead/{leadId} using an ID from modifiedLeadIds. If you need per-field feedback in the response itself, use the Sync API — it returns a remarks array.

Sync token used on Async endpoint ​

Symptom. Every request returns 403 with the plain-text body NOT_AUTHORIZED.

Cause. The token was generated as a Sync token. Sync and Async tokens are not interchangeable.

Fix. Generate a new token in Settings → Website and API → API token, selecting Async as the type. See Authentication.

Field API name does not exist in the workspace ​

Symptom. The lead is created, but a custom field is missing.

Cause. The key in fields did not match any field's API name in the workspace — for example, the field was renamed in the dashboard, or a typo in the key.

Fix. Confirm the field's API name under Settings → Lead Fields → field → Properties → API name. API names are case-sensitive.

Custom action that no longer exists ​

Symptom. The lead is created or updated, but the action is missing.

Cause. The custom action referenced by ACTION_<code> has been deleted or disabled in the workspace.

Fix. Confirm the action exists under Settings → Custom Actions and that the numeric code matches.

Rate limit exceeded ​

Symptom. Requests start returning 429 Too Many Requests.

Cause. The token has sent more than 18,000 requests in the last hour.

Fix. Slow the request rate or distribute load across multiple Async tokens (workspace cap: 3).