Intercom API (unofficial showcase)
POST/events

Submit a data event

Submits an event associated with a user, lead, or visitor for tracking. Include event_name, created_at, and one contact identifier: id, user_id, or email; event metadata supports up to 10 flat keys. Use an access token with write permissions and send the request as JSON.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 6 body fields
Intercom-Versionstringoptional
The API version to use. Defaults to 2.17 when omitted; supported values include 1.0 through 1.4 and 2.0 through 2.6.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Event details, including its name, UTC Unix timestamp, and one identifier for the associated contact.

event_namestringrequired
The name of the event that occurred. This is presented to your App's admins when filtering and creating segments - a good event name is typically a past tense 'verb-noun' combination, to improve readability, for example `updated-plan`.
created_atintegerrequired
The time the event occurred as a UTC Unix timestamp
user_idstringoptional
Your identifier for the user.
idstringrequired
The unique identifier for the contact (lead or user) which is given by Intercom.
emailstringoptional
An email address for your user. An email should only be used where your application uses email to uniquely identify users.
metadataobjectoptional
Optional metadata about the event.

2 status codes
202Returns an empty body when the event is accepted. Duplicate events may be ignored while still receiving this response.
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized; use an access token with write permissions. Include event_name, created_at, and one of id, user_id, or email to identify the contact. Keep metadata to 10 keys or fewer and do not send nested JSON structures.