Direct API Integration

The Direct API Integration lets you send identity, device, and event data to Conviso over HTTPS—without an SDK. Use it from any language or toolchain that can make HTTP requests (curl, server backends, ETL jobs, custom pipelines).

These endpoints are the same ones used by all Conviso SDKs under the hood.

Overview

Base URL:

https://api.opencdp.io/gateway/data-gateway

Endpoints:

Operation	Method	Path
Identify a person	POST	/v1/persons/identify
Track an event	POST	/v1/persons/track
Register a device	POST	/v1/persons/registerDevice
Send transactional email	POST	/v1/send/email
Send transactional push	POST	/v1/send/push

Prerequisites

Before calling the API, ensure you have:

1. An active Conviso Workspace.
2. A valid Conviso API Key (used to authenticate requests).

Authentication

Every request must include your Conviso API Key in the Authorization HTTP header, plus a JSON content type.

Required Headers

Authorization: <YOUR_CONVISO_API_KEY>
Content-Type: application/json

Keep Your API Key Secret

Never commit API keys to version control or expose them in client-side code. Prefer server-side callers and environment variables.

Identify a Person

Creates or updates a person profile.

• URL: POST https://api.opencdp.io/gateway/data-gateway/v1/persons/identify
• Body fields:
  • identifier (string, required) — Unique person ID (typically your internal user ID)
  • properties (object, optional) — Attributes to store on the person

Conviso recognizes common person attributes such as email, firstName/first_name, and lastName/last_name. Other keys are stored as custom attributes. See Person Field Mapping for accepted aliases.

Example Request

curl -X POST "https://api.opencdp.io/gateway/data-gateway/v1/persons/identify" \
  -H "Authorization: <YOUR_CONVISO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user123",
    "properties": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "plan": "premium"
    }
  }'

Example Payload

{
  "identifier": "user123",
  "properties": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "plan": "premium"
  }
}

Track an Event

Records a custom event for a person.

• URL: POST https://api.opencdp.io/gateway/data-gateway/v1/persons/track
• Body fields:
  • identifier (string, required) — Must match the identifier used in identify
  • eventName (string, required) — Event name (for example, purchase_completed)
  • properties (object, optional) — Event metadata

Example Request

curl -X POST "https://api.opencdp.io/gateway/data-gateway/v1/persons/track" \
  -H "Authorization: <YOUR_CONVISO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user123",
    "eventName": "purchase_completed",
    "properties": {
      "amount": 99.99,
      "currency": "USD",
      "order_id": "order_789"
    }
  }'

Example Payload

{
  "identifier": "user123",
  "eventName": "purchase_completed",
  "properties": {
    "amount": 99.99,
    "currency": "USD",
    "order_id": "order_789"
  }
}

Register a Device

Registers a device for a person so you can send push notifications.

• URL: POST https://api.opencdp.io/gateway/data-gateway/v1/persons/registerDevice
• Body fields:

Field	Type	Required	Description
identifier	string	Yes	Person ID (must match identify)
deviceId	string	Yes	Stable unique ID for the physical device
platform	string	Yes	ios, android, or web
fcmToken	string	Yes	Firebase Cloud Messaging token
name	string	No	Human-readable device name
osVersion	string	No	OS version
model	string	No	Device model
apnToken	string	No	Apple Push Notification token (iOS)
appVersion	string	No	App version
last_active_at	string	No	ISO timestamp of last activity
attributes	object	No	Extra device metadata

Device ID Must Stay Stable

deviceId must be unique per device and consistent across registrations. Do not generate a new ID for the same device on each call.

Example Request

curl -X POST "https://api.opencdp.io/gateway/data-gateway/v1/persons/registerDevice" \
  -H "Authorization: <YOUR_CONVISO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user123",
    "deviceId": "device_abc123",
    "platform": "ios",
    "fcmToken": "fcm_token_here",
    "apnToken": "apns_token_here",
    "osVersion": "17.0",
    "model": "iPhone 14 Pro",
    "appVersion": "1.2.3",
    "name": "John'\''s iPhone"
  }'

Example Payload

{
  "identifier": "user123",
  "deviceId": "device_abc123",
  "platform": "ios",
  "fcmToken": "fcm_token_here",
  "apnToken": "apns_token_here",
  "osVersion": "17.0",
  "model": "iPhone 14 Pro",
  "appVersion": "1.2.3",
  "name": "John's iPhone"
}

Minimal Payload

{
  "identifier": "user123",
  "deviceId": "device_abc123",
  "platform": "ios",
  "fcmToken": "fcm_token_here"
}

Trigger a Transactional Email

Sends a transactional email using a template from your Conviso workspace, or raw HTML.

• URL: POST https://api.opencdp.io/gateway/data-gateway/v1/send/email

Required Fields

Field	Type	Required	Description
to	string	Yes	Recipient email address
identifiers	object	Yes	Exactly one of id, email, or cdp_id
transactional_message_id	string | number	Yes*	Template ID from your workspace
from	string	Yes*	Sender address (required when not using a template)
subject	string	Yes*	Subject line (required when not using a template)
body	string	Yes*	HTML body (required when not using a template)
message_data	object	No	Liquid/template variables
reply_to	string	No	Reply-to address
bcc	string	No	BCC address
preheader	string	No	Email preheader text
language	string	No	Language code

* Use either transactional_message_id (template) or from + subject + body (raw HTML).

Template-Based Example

curl -X POST "https://api.opencdp.io/gateway/data-gateway/v1/send/email" \
  -H "Authorization: <YOUR_CONVISO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "identifiers": { "id": "user123" },
    "transactional_message_id": "WELCOME_EMAIL",
    "message_data": {
      "name": "John",
      "activation_link": "https://example.com/activate/abc123"
    }
  }'

{
  "to": "[email protected]",
  "identifiers": { "id": "user123" },
  "transactional_message_id": "WELCOME_EMAIL",
  "message_data": {
    "name": "John",
    "activation_link": "https://example.com/activate/abc123"
  }
}

Raw HTML Example

{
  "to": "[email protected]",
  "identifiers": { "email": "[email protected]" },
  "from": "[email protected]",
  "subject": "Welcome to Our Service",
  "body": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
}

Trigger a Transactional Push

Sends a transactional push notification to a person's registered device(s).

• URL: POST https://api.opencdp.io/gateway/data-gateway/v1/send/push

Required Fields

Field	Type	Required	Description
identifiers	object	Yes	Exactly one of id, email, or cdp_id
transactional_message_id	string | number	Yes	Push template ID from your workspace
title	string	No	Override template title
body	string	No	Override template body
message_data	object	No	Template variables / deep-link data

Device Must Be Registered

The person must have at least one device registered via /v1/persons/registerDevice before push delivery can succeed.

Example Request

curl -X POST "https://api.opencdp.io/gateway/data-gateway/v1/send/push" \
  -H "Authorization: <YOUR_CONVISO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": { "id": "user123" },
    "transactional_message_id": "WELCOME_PUSH",
    "title": "Welcome!",
    "body": "Thank you for joining us!",
    "message_data": {
      "deep_link": "/home"
    }
  }'

Example Payload

{
  "identifiers": { "id": "user123" },
  "transactional_message_id": "WELCOME_PUSH",
  "title": "Welcome!",
  "body": "Thank you for joining us!",
  "message_data": {
    "deep_link": "/home"
  }
}

Identifier Consistency

Use the same person identifier across identify, track, registerDevice, and transactional sends. Mixing IDs (for example, user ID on identify and email on track) splits activity across profiles.

For transactional email and push, pass that value inside identifiers as { "id": "user123" } (or { "email": "..." } / { "cdp_id": "..." }).

Troubleshooting

• 401 Unauthorized: Ensure your Conviso API key is valid and set in the Authorization header (raw key value, not a Bearer prefix unless your key already includes one).
• 400 Bad Request / Validation Error: Confirm required fields are present (identifier; for track also eventName; for registerDevice also deviceId, platform, and fcmToken; for transactionals also identifiers and transactional_message_id or raw email fields).
• Events Not Associated With a Person: Verify you are using the same identifier string that was used in identify.
• Push Not Delivered: Confirm the person has a registered device and that identifiers matches the ID used in registerDevice.

Related

• Node.js SDK — Typed client for the same endpoints
• PostHog Webhook — Ingest via PostHog instead of calling the API directly
• Person Field Mapping — Accepted person attribute names
• Identity and devices — Person ID vs device ID vs push token
• Transactionals — Creating transactional message templates in Conviso