TextKitDocs

Track a customer event

Records something a person did in your app and starts or advances the automations listening for it.

POST/v1/track

Body Parameters

  • eventstringrequired

    Letters, digits, and _ . : - At most 64 characters. Example: trial_started.

  • user_idstring

    At most 128 characters. Example: 123.

  • phonestring

    Example: +14155550132.

  • propertiesobject

    Up to 20 scalar values; usable as merge fields and in conditions.

Headers

  • Idempotency-Keystring

    At most 255 characters.

Details

Pass phone, user_id, or both; a call with both links them so later events need only user_id. Test keys reach sandbox automations, live keys live ones.

Supports Idempotency-Key. 100 calls per 10 seconds per key. Scope: automations.

(GET /events is the webhook event log, a different thing.)

Responses

  • 201TrackedEvent

    Recorded

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • idstring

    Example: tev_a1B2c3D4e5F6g7H8.

  • objecttracked_event
  • eventstring
  • user_idstring

    Nullable.

  • phonestring

    Null when user_id is not linked to a number yet (nothing could start). Nullable.

  • propertiesobject
  • testboolean
  • runs_startedarray of string

    Ids of the runs this event started.

  • runs_notifiedinteger

    Runs in progress for this person that recorded the event.

  • created_atstring (date-time)

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429

    Rate limit or quota exceeded

Idempotency

Send an Idempotency-Key header to make retries safe. For 24 hours the same key with the same body replays the original successful response (with Idempotent-Replayed: true); the same key with a different body returns 409. A failed request releases its key.