Skip to main content
Version: 1.0.0

OmniSegment External API

External Data Exchange APIs for audience import, purchase data import, and gift voucher import.

Common API Specifications​

Base URLs​

The OmniSegment API is available on different environments with the following base URLs:

  • Taiwan Production: https://api.omnisegment.com
  • Japan Production: https://jp.api.omnisegment.com
  • Staging Environment: https://staging.omnicloud.tech

In this documentation, all host names in the API endpoints are represented with the variable {API_HOST_NAME}, which should be replaced with the appropriate base URL for your environment.

Authentication​

The API uses multiple authentication methods:

  • API Key Authentication: Required for most external API endpoints
  • Session Authentication: For web-based applications
  • Basic Authentication: For legacy system integration

Rate Limiting​

API requests are subject to rate limiting to ensure system stability. Rate limits apply to the following endpoints:

  • /api/v1/interaction-report/
  • /api/v1/tracking-event-report/
  • /api/v1/products/import-event-registration-data/
  • /api/v1/products/import-product-guarantee-data/
  • /api/v1/products/import/
  • /api/import-gift-voucher/
  • /omnidata/show-market-report/
  • /api/import-purchase-data/
  • /ma_audience/import-audience/
  • /api/v1/beacon/track-event/

If you exceed the allowed rate limit, the API may return 429 (Too Many Requests) error code. Please implement appropriate retry logic with exponential backoff in your applications.

Response Format​

All API responses follow a standardized JSON format with consistent structure and appropriate HTTP status codes.

Success Response Format​

{
  "SUCCESS": true,
  "PAYLOAD": "xxxxxx"
}

Notes:

  • The value of key PAYLOAD contains the result of the called API
  • The value depends on each API specification
  • HTTP Status Code: 200

Failure Response Format​

{
  "SUCCESS": false,
  "ERR_MSG": "xxxxxx"
}

Notes:

  • The value of key ERR_MSG contains the error message
  • The value depends on each API specification
  • HTTP Status Codes: 400 (Bad Request), 403 (Forbidden), 500 (Internal Server Error)

Error Response Status Code Handbook​

Gateway and Service Errors:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Retry Policy: If you receive any of the above status codes (502, 503, 504), retry the request every five minutes until receiving a different status code or after retrying five times.

Authentication​

API Key authentication using X-OmniSegment-Api-Key header

Security Scheme Type:

apiKey

Header parameter name:

API Key Auth in Header