Skip to main content

Getting Started

Groovinads Edge API gives retailers a single, server-to-server REST surface for retail media integrations: send behavioral events and request ad renders from one place, with one auth, and one set of typed schemas.

tip

Use our Sandbox environment to start testing your integration.

What Edge API provides​

Three endpoints — ingestion, render, and discovery:

EndpointPurpose
POST /v1/eventsSend 1 to 500 behavioral events in a single call (page views, product views, cart, conversions). Returns 202 Accepted immediately.
POST /v1/renderRequest an ad render. Returns a renderable payload in one of three shapes: data, component, or html.
GET /v1/formatsList the ad formats accessible to your API key.

Where do I start?​

  1. Register as an Edge API user: get in touch with your assigned Customer Success or Sales Manager to request the registration.
  2. Generate an API Key (see Authentication Guide).
  3. Read the Event Model and the Render Descriptor to understand what you'll send and receive.
  4. Pick an SDK (JS, React, iOS, Android) — or call the API directly.

Making a request​

All URLs start with https://edge.groovinads.com/v1/ (SSL only!).

To send a batch of events — note that events[] accepts many events in a single call (up to 500):

curl -X 'POST' \
  'https://edge.groovinads.com/v1/events' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {"type":"page_view",    "uid":"user_123", "url":"https://shop.example.com/"},
      {"type":"product_view", "uid":"user_123", "sku":"ABC-001"},
      {"type":"cart",         "uid":"user_123", "items":[{"sku":"ABC-001","qty":2}]},
      {"type":"conversion",   "uid":"user_123", "idtransaction":"tx-9",
                              "goalvalue":99.90, "idpixel":"42",
                              "items":[{"sku":"ABC-001","qty":1,"subtotal":49.95}]}
    ]
  }'

To request an ad render:

curl -X 'POST' \
  'https://edge.groovinads.com/v1/render?format=component' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "id_format": 42,
    "id_shop": 7,
    "id_user": "user_123"
  }'

where SESSION_TOKEN is obtained as described in the Authentication Guide.

Authentication​

Edge API reuses the same authentication model as the rest of the Groovinads platform: you create a long-lived API Key in the admin panel, exchange it for a short-lived Session Token, and send the Session Token on every API call.

Read the Authentication Guide to get started.

Client account selection​

When making API calls on behalf of a specific client, include the id_client in the x-id-clients header:

-H 'x-id-clients: 123'

The header accepts one or more id_client values separated by commas.

Just JSON​

All data is sent and received as JSON. Attribute keys use snake_case. Set Content-Type: application/json; charset=utf-8 when POSTing.

HTTP Verbs​

VerbUsed for
POSTSending events, requesting renders, creating resources
GETRetrieving resources (e.g. listing your API keys)
PUTReplacing a resource
DELETEDeleting a resource

Sandbox​

Test against the sandbox environment without affecting any real data or live systems. Authentication mirrors production, but you must generate a separate API Key dedicated to the sandbox.

Access the sandbox by replacing the host:

URLs

Sandbox URL: https://edge-dev.groovinads.com/v1/

Production URL: https://edge.groovinads.com/v1/

Resources​

Help us make it better​

Please tell us how we can make Edge API better. If you have a specific feature request or if you found a bug, please contact us.