Getting Started with the Symbiosys API

The Symbiosys API enables retailers to programmatically integrate their advertising systems and workflows with the Symbiosys platform.

Retailers can use the API to manage advertisers and campaigns, access retailer-specific resources, and retrieve advertising performance data.

This guide covers the basic concepts required to authenticate with the API and make your first request.

API Version

The current version of the API is V3.

API requests use the V3 base path:

https://api.symbiosys.ai/v3/

For complete endpoint definitions, request and response schemas, and supported values, see the API Reference.

Authentication

The Symbiosys API uses API keys for authentication.

Include your API key in the x-api-key header with each request:

x-api-key: YOUR_API_KEY

Your API key determines your retailer context and the resources available to your integration.

Keep your API key secure and do not expose it in client-side applications or publicly accessible source code.

Make Your First Request

A good way to verify your credentials and begin exploring the API is to retrieve the advertisers configured for your retailer.

Send a request to the Advertisers endpoint:

GET /v3/advertiser/

Include your API key:

GET https://api.symbiosys.ai/v3/advertiser/
x-api-key: YOUR_API_KEY

A successful response returns advertisers available within your retailer context.

The advertiser IDs returned by this request can be used to manage advertiser configuration, retrieve campaigns, and access other advertiser-specific resources.

Pagination

List endpoints may return paginated results.

Use:

• limit to control the maximum number of results returned.

• offset to specify where the result set should begin.

For example:

GET /v3/advertiser/?limit=50&offset=0

To retrieve additional results, increment the offset:

GET /v3/advertiser/?limit=50&offset=50

Resource IDs

Resources managed through Symbiosys have internal Symbiosys IDs. Retailers may also maintain their own identifiers for these resources.

Where supported, the use_client_ids parameter determines which identifier should be used to resolve a resource.

When:

use_client_ids=false

IDs refer to Symbiosys resource IDs.

When:

use_client_ids=true

supported IDs can refer to identifiers provided by the retailer.

This allows retailers to integrate Symbiosys with existing systems without relying exclusively on Symbiosys-generated identifiers.

Where to Go Next

Once you've successfully authenticated:

Core Concepts
Understand how your retailer, advertisers, campaigns, and supporting resources relate to one another.

Campaigns
Learn how to create and manage campaigns for advertisers operating through your retail media program.

Reporting
Retrieve advertiser, campaign, and product-level advertising performance.

API Reference
Explore complete endpoint definitions, request and response schemas, and supported values in the API Reference.