External Screen IDs

External Screen IDs are a fallback option for legacy systems that cannot work with UUIDs. We strongly recommend using UUIDs for optimal performance.

Overview

By default, all screens in Adlocaite are identified by UUIDs (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890). UUIDs provide the best performance and are the recommended identification method.

External Screen IDs should only be used when:

• Your CMS or playout system cannot work with UUIDs
• You have a legacy system that requires its own identification schema
• Technical constraints prevent UUID adoption

Important: External IDs require account activation. Contact support@adlocaite.com to enable this feature for your publisher account.

Backward compatibility

All existing integrations continue to work - External IDs are completely optional. You can continue using UUIDs exclusively, use external IDs for all screens, or mix both approaches.

When to use external IDs

Use external Screen IDs only when:

Recommended: Use UUIDs

In all other cases, use UUIDs for optimal performance:

• Best API response times and throughput
• Optimized database queries and indexing
• Lower server load and resource consumption
• Future-proof architecture
• Standard practice across the industry

If you're starting a new integration or can modify your existing system, always choose UUIDs.

Setting up external IDs

External Screen IDs are stored in the external_id column of the screens table. After your account is activated, you can set them for your screens.

Database schema

-- The screens table includes an optional external_id column
CREATE TABLE screens (
  id UUID PRIMARY KEY,
  publisher_id UUID REFERENCES publishers(id),
  external_id TEXT,
  -- ... other columns
  UNIQUE(publisher_id, external_id)
);

Unique constraint

The combination of publisher_id and external_id must be unique. This means:

• Different publishers can use the same external ID
• You can use any string value (letters, numbers, hyphens, underscores, etc.)
• You cannot use the same external ID twice within your publisher account
• External IDs are optional - screens without an external_id can only be accessed via UUID

Setting external IDs

Contact your Adlocaite account manager or use the publisher dashboard to set external_id values for your screens. The process typically involves:

1. Providing a list of your screens with their desired external IDs
2. Validation to ensure uniqueness within your account
3. Database update to add the external IDs to your screens

Example external ID formats

External IDs can use any format that works for your organization:

Numeric: 12345, 00001, 99999
Descriptive: berlin-hauptbahnhof, times-square-north
Code-based: SCREEN-001, NYC-TS-01, LOC-42
Legacy system IDs: display_42, unit_alpha_3

Using external IDs in API calls

Once you've set up external IDs for your screens, you can use them in API calls by replacing the UUID path segment with /external-id/{your-external-id}.

Endpoint comparison

# Cacheable Assets
GET /screens/{uuid}/cacheable-assets

# Request Offer
GET /offers/request/{uuid}

# Cacheable Assets
GET /screens/external-id/{externalId}/cacheable-assets

# Request Offer
GET /offers/request/external-id/{externalId}

Example: Cacheable Assets with external ID

# Using UUID
curl "https://uamoseamohhsxwybytqx.supabase.co/functions/v1/api/screens/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cacheable-assets?min_bid_cents=100" \
  -H "Authorization: Bearer pub_1a2b3c4d5e6f7g8h9i0j"

# Using External ID
curl "https://uamoseamohhsxwybytqx.supabase.co/functions/v1/api/screens/external-id/SCREEN-001/cacheable-assets?min_bid_cents=100" \
  -H "Authorization: Bearer pub_1a2b3c4d5e6f7g8h9i0j"

Response (identical for both):

{
  "screen_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "SCREEN-001",
  "total_assets": 2,
  "assets": [
    {
      "asset_url": "https://storage.example.com/ad-12345.jpg",
      "cache_expires_at": "2025-10-07T16:30:00Z"
    },
    {
      "asset_url": "https://storage.example.com/ad-67890.mp4",
      "cache_expires_at": "2025-10-07T16:30:00Z"
    }
  ]
}

Example: Request Offer with external ID

# Using UUID
curl "https://uamoseamohhsxwybytqx.supabase.co/functions/v1/api/offers/request/a1b2c3d4-e5f6-7890-abcd-ef1234567890?min_bid_cents=150" \
  -H "Authorization: Bearer pub_1a2b3c4d5e6f7g8h9i0j"

# Using External ID
curl "https://uamoseamohhsxwybytqx.supabase.co/functions/v1/api/offers/request/external-id/SCREEN-001?min_bid_cents=150" \
  -H "Authorization: Bearer pub_1a2b3c4d5e6f7g8h9i0j"

Response (identical for both):

{
  "offer_id": "f1e2d3c4-b5a6-7890-abcd-ef9876543210",
  "bid_price_cents": 250,
  "asset_url": "https://storage.example.com/ad-99999.jpg",
  "expires_at": "2025-10-07T12:40:00Z",
  "billing_code": "ORG-PUB-12345"
}

Response includes both IDs

When you use an external ID in your API request, the response will include both the UUID (screen_id) and the external ID (external_id). This allows you to maintain references to both identifier systems if needed.

Important constraints

Uniqueness per publisher

Each external ID must be unique within your publisher account:

Publisher A uses external_id: "SCREEN-001"
Publisher B uses external_id: "SCREEN-001"
→ No conflict - different publishers

Publisher A uses external_id: "SCREEN-001" twice
→ Error - duplicate within same publisher

Optional field

The external_id field is optional:

• Screens without an external_id can only be accessed via UUID
• You can choose which screens get external IDs
• Mix both approaches within your account

Authentication required

Both UUID and external ID endpoints require the same authentication:

Authorization: Bearer {publisher_api_key}

URL encoding

If your external IDs contain special characters, ensure they are properly URL-encoded:

# Original external ID: berlin/hauptbahnhof-1
# URL-encoded: berlin%2Fhauptbahnhof-1

curl "https://.../external-id/berlin%2Fhauptbahnhof-1/cacheable-assets"

Supported endpoints

External IDs are currently supported for:

• GET /screens/external-id/{externalId}/cacheable-assets
• GET /offers/request/external-id/{externalId}

All other endpoints continue to use UUIDs exclusively.

Getting help

To set up external IDs for your screens:

1. Contact your Adlocaite account manager
2. Email support@adlocaite.com with your publisher ID and desired external IDs
3. Allow 1-2 business days for setup and validation

For technical questions about using external IDs in your integration, see our API documentation and Offers documentation.