This page documents the OneView API for sending events. In most cases, you’ll use the OneView Server Tag template which handles all API details automatically.
This API reference is for advanced use cases. If you’re using Google Tag Manager Server-Side, use the OneView Server Tag template instead of making direct API calls. Endpoint POST https://earth.oneviewhub.cloud/v1/sgtm Content-Type: application/json Authorization: Bearer YOUR_API_KEY
Authentication All requests must include an API key in the Authorization header.
Bearer token containing your OneView API key. Format: Bearer YOUR_API_KEY You can generate an API key from Settings > API Key in your OneView workspace.
Must be set to application/json
Optional. A unique key to ensure idempotency. Multiple requests with the same idempotency key are treated as duplicates, and only the first occurrence is processed. Use a unique identifier for each event (e.g., transaction ID, event timestamp + user ID).
Request Body The request body must be a JSON array containing one or more event objects.
[ { "event_name" : "purchase" , "event_payload" : { "transaction_id" : "T12345" , "value" : 99.99 , "currency" : "USD" , "items" : [ { "item_id" : "SKU123" , "item_name" : "Product Name" , "price" : 99.99 , "quantity" : 1 } ] }, "event_metadata" : { "consent" : { "analytics_storage" : true , "ad_storage" : true , "ad_user_data" : true , "ad_personalization" : true }, "identifiers" : [ { "alias_type" : "client" , "anonymous_client_id" : "1234567890.1234567890" }, { "alias_type" : "user" , "user_id" : "user_12345" }, { "alias_type" : "email" , "hashed_email" : "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3" } ] } } ]
Request Fields Event Object The name of the event (e.g., page_view, purchase, sign_up).
All event data including transaction details, item information, page data, etc. This should contain all fields from your Common Event Data. Show Common event_payload fields
Unique transaction identifier for purchase events.
Monetary value of the transaction.
Currency code (ISO 4217 format, e.g., USD, EUR).
Full URL of the page where the event occurred.
URL of the referring page.
User data object containing PII (automatically hashed by the template). User’s email address. Must be provided in plaintext; will be automatically hashed.
User’s phone number in E.164 format (e.g., +1234567890). Must be provided in plaintext; will be automatically hashed.
Address object containing first and last names (automatically hashed). User’s first name. Must be provided in plaintext; will be automatically hashed.
User’s last name. Must be provided in plaintext; will be automatically hashed.
Metadata about the event including consent and identifiers. Show event_metadata fields
Consent signals for the event. Controls whether the event is processed by OneView. true = granted, false = denied.
Controls whether Conversion API sends data to Media Partners. true = granted, false = denied.
Controls whether Enhanced Conversions include PII. true = granted, false = denied.
Controls personalized advertising flag in Conversion API. true = granted, false = denied.
Array of identifier objects used for identity resolution. Show Identifier object fields
Type of identifier. One of: client, user, organization, email, phone.
Client ID value (when alias_type is client).
User ID value (when alias_type is user).
Organization ID value (when alias_type is organization).
SHA-256 hashed email address (when alias_type is email).
SHA-256 hashed phone number in E.164 format (when alias_type is phone).
SHA-256 hashed phone number in numeric format (when alias_type is phone).
Response Success Response Error Responses { "error" : "Invalid request format" , "message" : "event_name is required" }
{ "error" : "Unauthorized" , "message" : "Invalid or missing API key" }
Status: 429 Too Many Requests
{ "error" : "Rate limit exceeded" , "message" : "Too many requests. Please try again later." }
PII Hashing Personally identifiable information (PII) must be hashed using SHA-256 before being sent to OneView:
Email addresses : Lowercased, trimmed, then hashedPhone numbers : Hashed in both E.164 format (with +) and numeric format (without +)Names : Lowercased, trimmed, then hashed
The OneView Server Tag template handles all PII hashing automatically. If making direct API calls, you must hash PII yourself using SHA-256.
Idempotency The API supports idempotency through the Idempotency-Key header. Multiple requests with the same idempotency key are treated as duplicates:
Only the first request is processed
Subsequent requests with the same key return success but are not processed
Idempotency keys should be unique per event
Use a combination of event timestamp and user ID, or a transaction ID, to generate unique idempotency keys.
Rate Limits The API has rate limits to ensure fair usage. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.
Rate limits vary by workspace plan. Contact support if you need higher limits.
Timeout The API has a timeout of 1500ms (1.5 seconds). Requests that exceed this timeout will fail.
Best Practices Use the Server Tag template instead of making direct API calls. It handles all formatting, hashing, and error handling automatically.
Include multiple identifiers in each event to improve identity resolution accuracy.
Set appropriate consent values based on user consent preferences to ensure compliance.
Use idempotency keys for critical events like purchases to prevent duplicate processing.
Next Steps 
