curl -X POST https://api.contactship.ai/v1/identify \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "GA1.1.1234567890.1726000000",
"contact": { "email": "ana@example.com", "phone": "+15555550102", "name": "Ana Pérez" }
}'
{
"statusCode": 200,
"data": {
"status": "linked",
"session_id": "GA1.1.1234567890.1726000000",
"contact": { "id": "33333333-3333-4333-8333-333333333333", "matched_by": "email", "created": false },
"pending_events": 3
}
}
Eventos
Identify a Session
Join the anonymous events of a visit to the contact who turned out to be behind it
POST
/
v1
/
identify
curl -X POST https://api.contactship.ai/v1/identify \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "GA1.1.1234567890.1726000000",
"contact": { "email": "ana@example.com", "phone": "+15555550102", "name": "Ana Pérez" }
}'
{
"statusCode": 200,
"data": {
"status": "linked",
"session_id": "GA1.1.1234567890.1726000000",
"contact": { "id": "33333333-3333-4333-8333-333333333333", "matched_by": "email", "created": false },
"pending_events": 3
}
}
Links a
session_id to a contact. The events that were waiting for that session (sent with the session_id and no contact data, answered as pending by Send events) move to the contact within a minute, with their original date, and show up in the contact’s activity marked Before identifying. Events sent afterwards with only that session_id go straight to the contact.
Call it when your site learns who the visitor is and has no event to send at that moment: a login, a sign-up, the end of a checkout. It does not take group: to link the contact to a company, send an event with it. If you do have an event with contact data, such as the purchase, sending it with the same session_id identifies the session too, and this call is not needed.
Part of the events add-on. Without it, this endpoint answers
403. See the events guide.Headers
Your organization API key. See API keys.
Body Parameters
The same
session_id sent with the anonymous events: a UUID your site keeps in the browser, or the Google Analytics client id. Up to 200 characters, no spaces.Who the visitor turned out to be, with at least one of
contact_id, external_id, phone (7 or more digits) or email. The contact is found the same way as in Send events.Create the contact when none matches. With
false, the session is only linked to a contact that already exists.Response
The response is{ "statusCode": 200, "data": object }. The fields below describe data.
linked: the session now belongs tocontact.id; its pending events move to the contact within a minute.already_linked: the session already belonged to another contact, which keeps it.conflictsays which.not_found: no contact matched and none was created; seereason.
The contact the session belongs to:
id, matched_by (contact_id, external_id, phone, email, or null when it was just created) and created. null when the status is not_found.For
not_found: not_found (no contact matched and create_contact was false), contact_limit_reached (your plan allows no more contacts) or ambiguous_email (the only data was an email shared by several contacts).Errors
| Status | When |
|---|---|
400 | session_id is missing or has a space inside, or contact has none of contact_id, external_id, phone (7 or more digits) or email. |
401 | The API key is missing or invalid. |
403 | The events add-on is not enabled for the organization. |
429 | The request limit for events was exceeded. It is the same budget as Send events. See Rate limits. |
curl -X POST https://api.contactship.ai/v1/identify \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "GA1.1.1234567890.1726000000",
"contact": { "email": "ana@example.com", "phone": "+15555550102", "name": "Ana Pérez" }
}'
{
"statusCode": 200,
"data": {
"status": "linked",
"session_id": "GA1.1.1234567890.1726000000",
"contact": { "id": "33333333-3333-4333-8333-333333333333", "matched_by": "email", "created": false },
"pending_events": 3
}
}