Conversions API

The Conversions API provides a structured way to send conversion data to Rokt similar to the existing Event API. It uses a defined set of fields instead of arbitrary key-value pairs, validates data formats and provides detailed feedback on issues without rejecting entire requests.

Endpoint

POST https://api.rokt.com/v1/conversions

Authentication

Reach out to your Rokt account manager to create a public and secret key pair for the accounts for which you would like to submit conversion events. These keys take the form of rpub- and rsec- respectively.

Name	Value
Rokt Public Key	rpub-******----**********
Rokt Secret Key	rsec-******----**********

Request

Headers

Name	Value	Description
`Content-Type`	`application/json`	Must be application/json.
`Authorization`	`Basic base64(rpub-...:rsec-...)`	Standard basic authentication header, with the credential value being a base64 encoding of `rpub-` and `rsec-` joined by a colon.

Body

The request body should be provided as JSON with the following fields:

Field	Type	Max length	Description
`accountId`*	String	64	Rokt Account ID
`test`	Boolean	—	When set to true, the request is validated without processing or ingesting any events. Use for testing your integration.
`events`*	List[Object]	100 items	Array of conversion events. Must contain at least one event.

Each object in the events array can contain the following fields:

Field	Type	Max length	Description
`conversionId`	String	255	Unique identifier for the conversion. Duplicate values within a request will cause subsequent events to be rejected.
`conversionType`*	String	255	Type of conversion (e.g., purchase, signup, subscription).
`eventTime`*	String	—	Time when the conversion event occurred (RFC3339 format). Cannot be in the future or more than 12 months old.
`roktId`	String	255	Rokt user identifier.
`email`	String	255	User email address (lowercase recommended for consistency with hashed values).
`emailsha256`	String	64	SHA256 hash of user email address (64 character hex string).
`rclid`	String	64	Rokt Click ID (SHA256 hash, 64 character hex string).
`mobile`	String	255	User mobile phone number.
`mobilesha256`	String	64	SHA256 hash of user mobile phone number (64 character hex string).
`firstName`	String	255	User first name.
`lastName`	String	255	User last name.
`billingZipcode`	String	255	User billing zip/postal code.
`firstNamesha256`	String	64	SHA256 hash of user first name (64 character hex string).
`lastNamesha256`	String	64	SHA256 hash of user last name (64 character hex string).
`billingZipcodesha256`	String	64	SHA256 hash of user billing zip/postal code (64 character hex string).
`ipAddress`	String	255	User IP address.
`userAgent`	String	1024	User agent string from the browser.
`value`	Number	—	Transaction value (0 to 1000000).
`ltv`	Number	—	Customer lifetime value (0 to 1000000).
`predictedLTV`	Number	—	Predicted customer lifetime value (0 to 1000000).
`currency`	String	255	Currency code (ISO 4217).
`quantity`	Integer	—	Quantity of items (minimum 0). Must be a whole number.
`productName`	String	255	Name of the product.
`sku`	String	255	Stock keeping unit identifier.
`paymentType`	String	255	Payment method type.
`margin`	Number	—	Profit margin (0 to 1000000).
`transactionId`	String	100	Unique transaction identifier.
`confirmationRef`	String	100	Confirmation reference number. Used for deduplication.
`customAttributes`	Object	—	Custom key-value pairs for additional data. • Maximum 10 keys • Keys must be alphanumeric (no spaces, underscores, or special characters) • Keys must not conflict with event schema field names • Key length maximum 255 characters • String values maximum 1024 characters

Identifier Validation

Each conversion event must include at least one of the following identifier combinations to enable proper matching and attribution:

Any of: roktId, email, emailsha256, rclid, mobile, mobilesha256
All of: firstName, lastName, billingZipcode
All of: firstNamesha256, lastNamesha256, billingZipcodesha256
All of: ipAddress, userAgent

Events that do not meet these requirements will fail validation.

Samples

Minimal example with required fields only:

{
  "accountId": "12345",
  "events": [
    {
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:00:00Z",
      "email": "user@example.com"
    }
  ]
}

Multiple events example:

{
  "accountId": "12345",
  "events": [
    {
      "conversionId": "evt_001",
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:00:00Z",
      "email": "alice@example.com"
    },
    {
      "conversionId": "evt_002",
      "conversionType": "signup",
      "eventTime": "2024-12-11T10:15:30Z",
      "email": "bob@example.com"
    },
    {
      "conversionId": "evt_003",
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:30:45Z",
      "email": "carol@example.com"
    }
  ]
}

Complete example with all available fields:

{
  "accountId": "12345",
  "events": [
    {
      "conversionId": "evt_123456",
      "conversionType": "purchase",
      "eventTime": "2024-09-11T10:00:00Z",
      "roktId": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "emailsha256": "d8a928b2043db77e340b523547bf16cb4aa483f0645fe0a290ed1f20aab76257",
      "rclid": "550e8400e29b41d4a716446655440001550e8400e29b41d4a716446655440001",
      "mobile": "+16175494599",
      "mobilesha256": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
      "firstName": "John",
      "lastName": "Doe",
      "billingZipcode": "12345",
      "firstNamesha256": "f1e2d3c4b5a698765432109876543210fedcba9876543210fedcba9876543210",
      "lastNamesha256": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "billingZipcodesha256": "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
      "ipAddress": "192.168.0.1",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "value": 99.99,
      "ltv": 499.99,
      "predictedLTV": 299.99,
      "currency": "USD",
      "quantity": 1,
      "productName": "Premium Widget",
      "sku": "WIDGET-001",
      "paymentType": "credit_card",
      "margin": 24.99,
      "transactionId": "txn_789012",
      "confirmationRef": "conf_456789",
      "customAttributes": {
        "source": "website",
        "campaignId": "summer2024",
        "isNewCustomer": true,
        "sessionId": "abc123def456",
        "couponCode": "SAVE20",
        "discountPercent": 15,
        "taxRate": 0.0825
      }
    }
  ]
}

Response

The API validates requests in two stages:

Request validation: checks authentication, JSON format, and required fields
Event validation: processes individual events if request validation passes

Status codes

HTTP response code	Description
200	Successfully processed conversion events (all or partial).
400	Bad request - validation errors or all events failed.
401	Unauthorized - invalid or missing authentication token.
403	Forbidden - token not authorized for this account.
413	Request Entity Too Large - request body exceeds 1MB limit.
429	Too Many Requests - rate limit exceeded.
500	Internal Server Error.
503	Service Unavailable.

Request validation errors

Response contains a data object with:

Field	Type	Description
`code`	String	Error code (e.g., EventsRequiredError, AccountIDRequiredError, InvalidJSONError).
`message`	String	Detailed error message.

Event processing results

Returns 200 (Success/Partial) if at least one event is valid, or 400 (Failure) if no events are valid.

All responses contain a data object with the following fields:

Field	Type	Description
`code`	String	Response status code (Success, Partial, or Failure).
`processedCount`	Number	Number of events successfully processed.
`invalidCount`	Number	Number of events that failed validation.
`errors`	List[Object]	Array of errors from event processing. Each object follows the error/warning schema below.
`warnings`	List[Object]	Array of warnings from event processing. Each object follows the error/warning schema below.

The warnings in the response will include the checks that have failed but are not severe enough to cause the whole conversion event to be rejected. They will not affect the invalidCount.

Each error and warning object in the errors and warnings arrays will include the conversionId field if it was provided in the corresponding request event. This helps identify which specific event caused the issue.

Error/warning object schema:

Field	Type	Description
`conversionId`	String	Conversion ID if present in the event.
`eventIndex`	Number	Position of the event in the request array (starting from 0).
`field`	String	Field name that caused the error or warning.
`message`	String	Error or warning message.

Samples

Request validation error:

{
  "data": {
    "code": "InvalidAccountIDError",
    "message": "Account ID is invalid"
  }
}

Success (all events valid):

{
  "data": {
    "code": "Success",
    "processedCount": 1,
    "invalidCount": 0
  }
}

Partial (some events valid):

{
  "data": {
    "code": "Partial",
    "processedCount": 1,
    "invalidCount": 1,
    "errors": [
      {
        "eventIndex": 1,
        "field": "conversionType",
        "message": "conversionType is required"
      },
      {
        "eventIndex": 1,
        "field": "eventTime",
        "message": "eventTime is required"
      }
    ]
  }
}

Failure (all events invalid):

{
  "data": {
    "code": "Failure",
    "processedCount": 0,
    "invalidCount": 1,
    "errors": [
      {
        "eventIndex": 0,
        "field": "eventTime",
        "message": "must be a valid RFC3339 timestamp"
      }
    ]
  }
}

Endpoint​

Authentication​

Request​

Headers​

Body​

Samples​

Response​

Status codes​

Request validation errors​

Event processing results​

Samples​

Endpoint

Authentication

Request

Headers

Body

Samples

Response

Status codes

Request validation errors

Event processing results

Samples