Skip to Content
JourneyKit
IntegrationIngest API

POST /identify

POST /api/ingest/identify
Authorization: Bearer jk_live_…
Content-Type: application/json

Body

{
  "contactId": "user-123",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "properties": { "firstName": "Ada", "plan": "trial", "company": "Acme" }
}
FieldType
contactIdstring (1–255)Required. Your id for the person.
emailemail stringWhere workflow emails go by default. Sending it as properties.email works the same, the two are kept in sync.
namestring (1–255)Display name.
propertiesobjectMerged into the contact's properties. Default {}.

Semantics:

  • The contact is created if unknown.
  • email and name are kept when a later call omits them (never blanked by absence).
  • properties merge shallowly: keys you send replace those keys; keys you don't send are untouched.
  • Unknown property keys are accepted and registered as undefined property definitions.

The browser SDK's identify(contactId, { email, name, ...properties }) sends exactly this: email and name are lifted out, the rest become properties.

Response

200 OK

{ "id": "3f9c…" }

id is JourneyKit's internal id for the contact (the one used in webhook payloads); you keep using your own contactId everywhere else.

On this page