Send Events

curl -X POST https://api.contactship.ai/v1/events \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "purchase",
        "event_id": "order-10025",
        "occurred_at": "2026-09-20T15:04:05Z",
        "contact": { "phone": "+15555550102", "email": "ana@example.com", "name": "Ana Pérez" },
        "params": {
          "transaction_id": "10025",
          "value": 41.90,
          "currency": "USD",
          "items": [{ "item_id": "PIZZA-L", "item_name": "Large pizza", "quantity": 2 }]
        }
      },
      {
        "event_name": "Add To Cart",
        "session_id": "GA1.1.1234567890.1726000000",
        "params": { "item_name": "Large pizza" }
      }
    ]
  }'

{
  "statusCode": 200,
  "data": {
    "summary": { "received": 2, "created": 1, "unresolved": 0, "pending": 1, "duplicate": 0, "rejected": 0, "invalid": 0, "contacts_created": 1 },
    "results": [
      {
        "index": 0,
        "event_id": "order-10025",
        "event_name": "purchase",
        "status": "created",
        "contact": { "id": "33333333-3333-4333-8333-333333333333", "matched_by": null, "created": true }
      },
      {
        "index": 1,
        "event_id": null,
        "event_name": "add_to_cart",
        "original_event_name": "Add To Cart",
        "status": "pending"
      }
    ]
  }
}

POST

events

curl -X POST https://api.contactship.ai/v1/events \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "purchase",
        "event_id": "order-10025",
        "occurred_at": "2026-09-20T15:04:05Z",
        "contact": { "phone": "+15555550102", "email": "ana@example.com", "name": "Ana Pérez" },
        "params": {
          "transaction_id": "10025",
          "value": 41.90,
          "currency": "USD",
          "items": [{ "item_id": "PIZZA-L", "item_name": "Large pizza", "quantity": 2 }]
        }
      },
      {
        "event_name": "Add To Cart",
        "session_id": "GA1.1.1234567890.1726000000",
        "params": { "item_name": "Large pizza" }
      }
    ]
  }'

{
  "statusCode": 200,
  "data": {
    "summary": { "received": 2, "created": 1, "unresolved": 0, "pending": 1, "duplicate": 0, "rejected": 0, "invalid": 0, "contacts_created": 1 },
    "results": [
      {
        "index": 0,
        "event_id": "order-10025",
        "event_name": "purchase",
        "status": "created",
        "contact": { "id": "33333333-3333-4333-8333-333333333333", "matched_by": null, "created": true }
      },
      {
        "index": 1,
        "event_id": null,
        "event_name": "add_to_cart",
        "original_event_name": "Add To Cart",
        "status": "pending"
      }
    ]
  }
}

Records up to 100 events per request, each tied to a contact. An event is an event_name plus free-form params, following Google Analytics 4 conventions: a purchase in your e-commerce, an order in your POS, a form, a visit, a step in Make or n8n. Events show up in the contact’s activity and can be used to segment and report. Events from visitors who have not identified yet can be sent too: with a session_id and no contact data, they wait until the session is identified and then move to the contact. See the events guide.

Events are an add-on. If your organization does not have it enabled, this endpoint answers 403. Ask ContactShip support to turn it on. See the events guide for a walkthrough.

Use Cases

Send purchases, carts, sign-ups or any business action from your own systems
Keep what a visitor did before logging in or buying, and join it to the contact when they do
Load past orders with their original date to segment and report on history
Keep contacts in sync: a new customer in your system becomes a contact in ContactShip

Headers

string

requerido

Your organization API key. See API keys.

Body Parameters

array

requerido

Between 1 and 100 events. Each one is validated and answered on its own: a malformed event does not reject the others.

Mostrar event object

string

requerido

What happened. It is normalized to lowercase snake_case before it is stored: Add To Cart, add-to-cart, addToCart and AddToCart are all stored as add_to_cart, and Compra Realizada as compra_realizada. Accents are dropped and words split on capitals, spaces, hyphens and dots. The normalized name must start with a letter and be up to 40 characters long. Use GA4 names where they apply (purchase, add_to_cart, begin_checkout, sign_up). Names starting with cs_ are reserved for ContactShip.

string

Your identifier for the event, unique across all your events: build it from the event and your record’s id, such as purchase-10025. Up to 200 characters, no spaces, the same on every retry. Sending the same event_id again does not duplicate the event: its result is duplicate. Recommended, so failed requests can be retried safely.

string

When it happened, in ISO 8601. Defaults to the time the request arrives. Dates from year 2000 up to 24 hours in the future are accepted.

object

Who it happened to, with at least one of contact_id, external_id, phone (7 or more digits) or email. Required unless the event brings a session_id: then it can be left out and the event waits for the session to be identified.

Mostrar contact object

string

The contact’s id in ContactShip (UUID).

string

The contact’s id in your system, up to 200 characters. It is linked to the contact the first time an event brings it together with data that finds the contact.

string

Phone number, preferably in international format (+573001234567). Compared by its last 10 digits.

string

Email address. Compared case-insensitively.

string

Name used if the contact has to be created.

string

Country used if the contact has to be created.

boolean

predeterminado:"true"

With false, the event is only added to contacts that already exist. Anonymous events never create contacts.

string

The visit the event happened in, the same in all its events: a UUID your site keeps in the browser, or the Google Analytics client id. Up to 200 characters, no spaces. An event with a session_id and no contact data is kept as pending for up to 30 days and moves to the contact, with its original date, when the session is identified: by a later event with the same session_id and contact data, or by Identify a session. Events sent afterwards with only that session_id go straight to the contact. Never use personal data, such as an email, as the session id.

object

Anything you want to keep about the event, in any shape, up to 32,000 characters.

number

The event’s value. Defaults to params.value. Numeric strings are accepted.

string

ISO 4217 code (USD, COP, MXN). Defaults to params.currency. Amounts in different currencies are never added together in reports.

object

The contact’s company: { "id": "...", "name": "...", "properties": {} }. id is required: the company’s id in your system, not its name, up to 200 characters. The first event with an id creates the company and links the contact to it; later ones update its name and add to its properties. See Companies.

array

Up to 10 links to the same thing in your systems, such as the ticket or the invoice: [{ "url": "https://...", "label": "Invoice 10025" }]. url is required, up to 2,000 characters, and must start with http:// or https://: anything else (javascript:, data:, no scheme) makes the event invalid, with a message that says which link. label is optional, up to 200 characters; without it the address is shown. The links are shown with the event, in the contact’s activity, and open in a new tab. See Links to your systems.

Body examples

Full bodies for the most common cases. You can mix events of different kinds in the same array, up to 100 per request. More examples (checkout, refund, sign-up, existing contacts only) are in the events guide.

{
  "events": [
    {
      "event_name": "purchase",
      "event_id": "order-10025",
      "occurred_at": "2026-09-20T15:04:05-05:00",
      "contact": {
        "external_id": "customer-4821",
        "phone": "+573001234567",
        "email": "ana@example.com",
        "name": "Ana Pérez"
      },
      "params": {
        "transaction_id": "10025",
        "value": 41.90,
        "currency": "USD",
        "payment_method": "card",
        "items": [
          { "item_id": "PIZZA-L", "item_name": "Large pizza", "price": 18.50, "quantity": 2 },
          { "item_id": "SODA-15", "item_name": "Soda 1.5 L", "price": 4.90, "quantity": 1 }
        ]
      },
      "links": [
        { "url": "https://billing.example.com/invoices/10025", "label": "Invoice 10025" }
      ]
    }
  ]
}

{
  "events": [
    {
      "event_name": "add_to_cart",
      "event_id": "cart-8812-1",
      "contact": { "email": "ana@example.com" },
      "params": {
        "value": 18.50,
        "currency": "USD",
        "items": [{ "item_id": "PIZZA-L", "item_name": "Large pizza", "price": 18.50, "quantity": 1 }]
      }
    }
  ]
}

{
  "events": [
    {
      "event_name": "generate_lead",
      "event_id": "lead-55310",
      "contact": { "phone": "+573001234567", "email": "ana@example.com", "name": "Ana Pérez" },
      "params": { "form_name": "Business quote", "interest": "Pro plan", "utm_source": "facebook" }
    }
  ]
}

{
  "events": [
    {
      "event_name": "page_view",
      "session_id": "GA1.1.1234567890.1726000000",
      "params": { "page_location": "https://yourstore.com/pizzas", "page_title": "Pizzas" }
    },
    {
      "event_name": "view_item",
      "session_id": "GA1.1.1234567890.1726000000",
      "params": { "item_id": "PIZZA-L", "item_name": "Large pizza" }
    }
  ]
}

{
  "events": [
    {
      "event_name": "purchase",
      "event_id": "order-9001",
      "occurred_at": "2025-11-03T19:20:00-05:00",
      "contact": { "phone": "+573001234567", "name": "Ana Pérez" },
      "params": { "transaction_id": "9001", "value": 35.50, "currency": "USD" }
    },
    {
      "event_name": "purchase",
      "event_id": "order-9377",
      "occurred_at": "2026-01-15T12:05:00-05:00",
      "contact": { "phone": "+573001234567", "name": "Ana Pérez" },
      "params": { "transaction_id": "9377", "value": 52.90, "currency": "USD" }
    }
  ]
}

value and currency can go inside params, as in GA4, or at the same level as event_name; when both are sent, the outer one wins. Only the top-level fields of params can be used to filter and split custom reports: to report by product, also send it at the top level, such as "product_name": "Large pizza".

How the contact is found

The contact is looked up in this order, keeping the first match: contact_id, then external_id, then phone (last 10 digits, so +57 300 123 4567, 573001234567 and 3001234567 match), then email. When none of them is sent, the event’s session_id is used if that session was already identified.

If several contacts share the phone, the event goes to the one with the most recent conversation or call.
An email shared by several contacts is not used.
If the phone and the email point to different contacts, the phone wins and conflict says so.
If nothing matches and the event brings a phone or an email, the contact is created (unless create_contact is false), named after contact.name, or else the email or the phone. This uses your plan’s contact quota.
Contacts are never merged. A contact that is found only gets its phone or email filled in when it was empty.

Anonymous events limits

An organization accepts up to 100,000 anonymous events a day. Past that, they are rejected with anonymous_daily_limit until the next day. Contact support if you need more.
Requests carrying anonymous events use an extra request budget, smaller than the one for events with contact data. See Rate limits.

Response

The response is { "statusCode": 200, "data": object }, with one result per event in the order they were sent. The fields below describe data.

object

Counts for the request: received, created, unresolved, pending, duplicate, rejected, invalid and contacts_created.

array

One result per event.

Mostrar result object

number

Position of the event in the request.

string

The event_id you sent, or null.

string

The name the event is stored under, already normalized. Missing only when the name could not be read at all.

string

Only when normalizing changed the name: exactly what you sent, such as Add To Cart for add_to_cart.

string

created: stored on contact.id.
pending: anonymous; kept until its session is identified, for up to 30 days.
unresolved: stored without a contact; see reason.
duplicate: an event with that event_id already exists; not stored again.
rejected: not stored; see reason.
invalid: not stored; see errors.

string

contact_limit_reached (unresolved): your plan allows no more contacts.
ambiguous_email (unresolved): the only data was an email shared by several contacts.
not_found (unresolved): no contact matched and create_contact was false.
no_identity (rejected): no contact_id, external_id, phone, email or session_id.
anonymous_daily_limit (rejected): the organization reached its daily cap of anonymous events.
event_name_limit (rejected): the organization reached 500 distinct event names.

string[]

What to fix, for invalid events.

object

For created events: id, matched_by (contact_id, external_id, phone, email, session, or null when it was just created) and created.

object

Present when something was ambiguous: phone_shared_by, email_shared, email_points_to or contact_id_not_found.

Errors

Status	When
`400`	The body is not `{ "events": [...] }` with 1 to 100 objects.
`401`	The API key is missing or invalid.
`403`	The events add-on is not enabled for the organization.
`429`	The request limit for this endpoint was exceeded. It has its own budget, separate from the rest of the API, and requests with anonymous events have an extra one. See Rate limits.

curl -X POST https://api.contactship.ai/v1/events \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "purchase",
        "event_id": "order-10025",
        "occurred_at": "2026-09-20T15:04:05Z",
        "contact": { "phone": "+15555550102", "email": "ana@example.com", "name": "Ana Pérez" },
        "params": {
          "transaction_id": "10025",
          "value": 41.90,
          "currency": "USD",
          "items": [{ "item_id": "PIZZA-L", "item_name": "Large pizza", "quantity": 2 }]
        }
      },
      {
        "event_name": "Add To Cart",
        "session_id": "GA1.1.1234567890.1726000000",
        "params": { "item_name": "Large pizza" }
      }
    ]
  }'

{
  "statusCode": 200,
  "data": {
    "summary": { "received": 2, "created": 1, "unresolved": 0, "pending": 1, "duplicate": 0, "rejected": 0, "invalid": 0, "contacts_created": 1 },
    "results": [
      {
        "index": 0,
        "event_id": "order-10025",
        "event_name": "purchase",
        "status": "created",
        "contact": { "id": "33333333-3333-4333-8333-333333333333", "matched_by": null, "created": true }
      },
      {
        "index": 1,
        "event_id": null,
        "event_name": "add_to_cart",
        "original_event_name": "Add To Cart",
        "status": "pending"
      }
    ]
  }
}

Documentación API

Voz

WhatsApp (WABA)

Canales y conversaciones

Organización

Agentes

Contactos

Eventos

Etiquetas

Llamadas

Tareas

Números de teléfono

Use Cases

Headers

Body Parameters

Body examples

How the contact is found

Anonymous events limits

Response

Errors