Getting Started

Welcome to our SDK (Software Development Kit) documentation, tailored for integration with third-party DSPs (Demand-Side Platforms) compliant with OpenRTB 2.6. Our platform facilitates the exchange of DOOH (Digital Out-of-Home) inventory between advertisers and publishers.

This documentation outlines the functionalities provided by the SSP API for integrating creatives into your platform. The SSP API allows you to ingest creatives, manage them, and retrieve necessary information using REST endpoints.

My tip

Creatives can be ingested into the system via API or bid response. All creatives undergo an audit process, therefore, we strongly recommend using API creatives for pre-approval.

Where do I start?

Want to get started with API integration? Here's a quick check list:

1. Register as an SSP API user in Groovinads. (send an email to ssp_registration@groovinads.com)
2. Generate an API Key
3. Read the API docs to understand how to use this API.

Making a request

All URLs start with https://api.groovinads.com/v2/. (SSL only!).

If we change the API in backward-incompatible ways, we'll bump the version marker and maintain stable support for the old URLs.

For example, to make a request for the details on a creative with the id 123456 via the API you would do the following in curl:

curl -X 'GET' \
  'https://api.groovinads.com/v2/ssp/creatives/1234' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SESSION_TOKEN'

where SESSION_TOKEN is the session token you requested (see Authentication).

To create something, you have to include the Content-Type header and the JSON data:

curl -X 'POST' \
  'https://api.groovinads.com/v2/ssp/creatives/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "id_creative": 123455,
  "advertiser_name": "the advertiser",
  "advertiser_url": "https://the.advertiser.com/",
  "type": "video",
  "video_format": "vast"
}'

Authentication

We follow the OAuth 2 framework for letting users authorize to use Groovinads API. A user authenticates using Google, LinkedIn and other oAuth providers. Once authenticated, the user can request an API Key (or what we call oAuth Token), which is generated only once, and acts as the API credential you will use to request the required Sessions tokens whenever you need to make API calls via your integration.

Read the authentication guide to get started.

Distinction between API Users and Clients

In the Groovinads SSP API, there is an important distinction between API Users and Clients:

• API Users are the technical users that authenticate and interact with the API. These users go through the authentication flow described above using OAuth providers and obtain API Keys to access the system.

• Clients are business entities in Groovinads that represent external billable customers to whom we provide services. A client could be an advertising agency, publisher, or other business partner.

The relationship between API Users and Clients is managed through pre defined admin groups. These groups determine which client(s) a particular API user has access to. An API user may be granted access to one or multiple clients depending on their admin group permissions.

This separation allows for proper access control and billing while enabling technical users to integrate with our API on behalf of the business clients they represent.

Client account selection

When making API calls that involve performing an action (such as GET, POST, etc.) on a specific CLIENT, you must include the id_client parameter in the request headers. This is done using a header called x-id-clients. The value of this header should be a string containing one or more id_client values, separated by commas.

For example, if you are making a request on behalf of clients with IDs 123 and 456, your header should look like this: -H 'x-id-clients: 123,456'

Just JSON

All data is sent and received as JSON. Our format is to have no root element and we use snake_case to describe attribute keys. This means that you have to send Content-Type: application/json; charset=utf-8 when POSTing or PUTing data into the SSP API.

Rate limiting

In order to control the incoming traffic from the API, you can perform a limited number of requests in a given period of time. Currently, the approach used to limit the API usage is based on a rate of 5 requests per second, which means that you can perform up to 300 requests per minute, without getting a 429 Too Many Requests error. If you need a higher rate limit for your specific use case, please contact us at dev@groovinads.com.

HTTP Verbs

Where possible, API v2 strives to use appropriate HTTP verbs for each action.

• POST : Used for creating resources or requesting filtered lists.

API resources

• SDK