Skip to main content

Getting Started

This guide walks through authenticating with the SpotLight API, selecting a team, and creating your first order. For full route documentation see the API reference.

Prerequisites​

  • A SpotLight account with API access enabled for your team
  • An API token (x-access-token) issued by ZeroLight — contact your Account Executive if you do not have one

API basics​

ItemValue
Base URLhttps://spotlightsuite.com
Route prefix/api/external/
Content typeapplication/vnd.api+json
Auth headerx-access-token: <YOUR_TOKEN>
Team headerx-team-id: <WORKING_TEAM_ID> (required on most routes)

All requests must use HTTPS.

Step 1: List your teams​

The teams endpoint does not require x-team-id. Use it to discover which teams your token can access.

curl -s https://spotlightsuite.com/api/external/teams \
  -H "Content-Type: application/vnd.api+json" \
  -H "x-access-token: <YOUR_TOKEN>"

Example response:

{
  "data": [
    {
      "teamId": "5ea96707dd4089351817c0dc",
      "teamOem": "zerolight",
      "teamName": "ZeroLight PreLive",
      "serviceType": "Palette"
    }
  ]
}

Note the teamId and serviceType for the team you want to work with. serviceType is either Palette or OmniStream and affects which parameters are required when creating orders.

Step 2: Inspect team assets​

Retrieve assets available on a team before creating an order. The URL team ID must match the x-team-id header.

curl -s https://spotlightsuite.com/api/external/teams/<WORKING_TEAM_ID> \
  -H "Content-Type: application/vnd.api+json" \
  -H "x-access-token: <YOUR_TOKEN>" \
  -H "x-team-id: <WORKING_TEAM_ID>"

Use an asset UID from the response in your order request.

Step 3: Create your first order​

The example below creates a Gallery (frame_pack) order for a Palette team. Adjust type, asset, template, and configuration fields for your use case — see Order types in the API reference.

const response = await fetch('https://spotlightsuite.com/api/external/orders/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/vnd.api+json',
    'x-access-token': '<YOUR_TOKEN>',
    'x-team-id': '<WORKING_TEAM_ID>',
  },
  body: JSON.stringify({
    data: {
      type: 'frame_pack',
      asset: 'lamborghini%20urus%202018',
      prcodes: 'F14 0E0E,GPC0PC0,GPGMPGM,GPGOPGO,GPGYPGY,GPH8PH8,GPH9PH9',
      template: 'frame-pack-lamborghini-urus-2018-pilot',
    },
  }),
});

const result = await response.json();

if (result.errors) {
  console.error(result.errors);
} else {
  console.info('Order accepted:', result.data.id);
}

A successful request returns 202 Accepted — the order is queued for processing, not completed immediately.

Step 4: Check order status​

Poll order status using the ID returned from creation, or configure a webhook callback for completion notification.

curl -s https://spotlightsuite.com/api/external/orders/<ORDER_ID>/status \
  -H "Content-Type: application/vnd.api+json" \
  -H "x-access-token: <YOUR_TOKEN>" \
  -H "x-team-id: <WORKING_TEAM_ID>"

Next steps​