Events

Things a Contact or organization did. Each route takes one Event or an array of them, and occurredAt is required on every Event. When any Event names a Contact or organization that does not exist, the whole request is refused with 422, nothing is recorded, and the body lists which Events failed to match.

Record Events for a Contact by Throughline id

POST /v1/events/by-contact-id

Names the Contact by the id Throughline gave it.

Requires the events:write scope.

Request body

One object as below, or an array of them.

Field	Type	Required
contactId	string (uuid)	Required
organizationExternalId	string	Optional
eventName	string	Required
occurredAt	string (date-time)	Required
dedupKey	string	Optional
properties	object	Optional

Responses

• 202 Accepted: accepted
• 400 Bad Request: code, message
• 402 Payment Required
• 403 Forbidden: code, message
• 422 Unprocessable Entity: code, message, unresolved
• 429 Too Many Requests: code, message

Example

curl -X POST https://server.api.throughline.dk/v1/events/by-contact-id \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "0192f5a4-3c1e-7d2a-9b7e-1f2a3b4c5d6e",
  "organizationExternalId": "acme",
  "eventName": "plan_upgraded",
  "occurredAt": "2026-10-03T12:00:00Z",
  "dedupKey": "plan-upgrade-user-42-2026-10-03",
  "properties": {
    "plan": "pro"
  }
}'

Record Events for a Contact by your own id

POST /v1/events/by-external-id

Names the Contact by the externalId you gave it.

Requires the events:write scope.

Request body

One object as below, or an array of them.

Field	Type	Required
contactExternalId	string	Required
organizationExternalId	string	Optional
eventName	string	Required
occurredAt	string (date-time)	Required
dedupKey	string	Optional
properties	object	Optional

Responses

• 202 Accepted: accepted
• 400 Bad Request: code, message
• 402 Payment Required
• 403 Forbidden: code, message
• 422 Unprocessable Entity: code, message, unresolved
• 429 Too Many Requests: code, message

Example

curl -X POST https://server.api.throughline.dk/v1/events/by-external-id \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "contactExternalId": "user-42",
  "organizationExternalId": "acme",
  "eventName": "plan_upgraded",
  "occurredAt": "2026-10-03T12:00:00Z",
  "dedupKey": "plan-upgrade-user-42-2026-10-03",
  "properties": {
    "plan": "pro"
  }
}'

Record Events for a Contact by email

POST /v1/events/by-email

Names the Contact by email address.

Requires the events:write scope.

Request body

One object as below, or an array of them.

Field	Type	Required
contactEmail	string	Required
organizationExternalId	string	Optional
eventName	string	Required
occurredAt	string (date-time)	Required
dedupKey	string	Optional
properties	object	Optional

Responses

• 202 Accepted: accepted
• 400 Bad Request: code, message
• 402 Payment Required
• 403 Forbidden: code, message
• 422 Unprocessable Entity: code, message, unresolved
• 429 Too Many Requests: code, message

Example

curl -X POST https://server.api.throughline.dk/v1/events/by-email \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "contactEmail": "ada@example.com",
  "organizationExternalId": "acme",
  "eventName": "plan_upgraded",
  "occurredAt": "2026-10-03T12:00:00Z",
  "dedupKey": "plan-upgrade-user-42-2026-10-03",
  "properties": {
    "plan": "pro"
  }
}'

Record Events for an organization

POST /v1/events/by-organization

Names the organization by your own id, and optionally the Contact who acted.

Requires the events:write scope.

Request body

One object as below, or an array of them.

Field	Type	Required
organizationExternalId	string	Required
contactId	string (uuid)	Optional
eventName	string	Required
occurredAt	string (date-time)	Required
dedupKey	string	Optional
properties	object	Optional

Responses

• 202 Accepted: accepted
• 400 Bad Request: code, message
• 402 Payment Required
• 403 Forbidden: code, message
• 422 Unprocessable Entity: code, message, unresolved
• 429 Too Many Requests: code, message

Example

curl -X POST https://server.api.throughline.dk/v1/events/by-organization \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "organizationExternalId": "acme",
  "contactId": "0192f5a4-3c1e-7d2a-9b7e-1f2a3b4c5d6e",
  "eventName": "plan_upgraded",
  "occurredAt": "2026-10-03T12:00:00Z",
  "dedupKey": "plan-upgrade-user-42-2026-10-03",
  "properties": {
    "plan": "pro"
  }
}'