Pitfalls

The Async API is fire-and-forget — a 200 response confirms only that the request was queued. Validation failures during background processing are not surfaced. The pitfalls below are the most common reasons leads or actions appear to be ingested but never show up in the workspace.

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

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

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

- "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 of creation

Symptom. Leads appear to be ingested per the API response, but never show up in the dashboard.

Cause. The 200 response confirms only that the request was queued for background processing. Any failure after that point — wrong field type, missing identifier, missing prefix — is not reported back.

Fix. Treat 200 as receipt, not success. Verify ingestion through the dashboard or the Sync API. For workflows that require per-request confirmation, use the Sync API instead.

Sync token used on Async endpoint

Symptom. Every request returns 401 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).