Offers

Offers are the core of the Adlocaite API - they represent real-time opportunities to display advertisements on specific screens. When you request an offer for a screen, our matching engine evaluates available ads and returns the best match with pricing and timing information.

The offer model

The offer model contains all the information you need to evaluate and respond to a programmatic DOOH advertising opportunity.

Properties

Name
offer_id
Type
string
Description
Unique identifier for the offer.
Name
bid_price_cents
Type
integer
Description
Bid price offered in cents.
Name
asset_url
Type
string
Description
Direct URL to the advertisement asset (image/video).
Name
expires_at
Type
timestamp
Description
When this offer expires and must be responded to.
Name
billing_code
Type
string | null
Description
Billing code for the organization-publisher combination. Always returns the currently configured value. Can be null if no code is configured.
Name
vast
Type
string
Description
Optional. VAST 4.0 XML string containing advertisement metadata and tracking events. Only included when the vast=true query parameter is used in the request.

Screen identification

You can identify screens in offer requests using either UUIDs (recommended) or external IDs (fallback only).

UUID (recommended)

Use UUIDs for optimal performance. This is the recommended method for all integrations:

GET /offers/request/a1b2c3d4-e5f6-7890-abcd-ef1234567890

External ID (fallback only)

Performance Impact: External IDs significantly reduce API performance. Only use if your CMS/playout system cannot support UUIDs:

GET /offers/request/external-id/SCREEN-001

Learn more: See the External Screen IDs documentation for requirements, setup instructions, and important performance considerations.

Request an offer

This endpoint supports both UUID (recommended for best performance) and External ID (fallback only for legacy systems) identification methods.

Using UUID

Demo/Test Functionality

Two ways to get demo responses for testing and development:

Option 1: Use special demo Screen-ID: test-display-test

Option 2: Add ?demo=true parameter to any Screen-ID

• Returns demo offer: test-offer-test
• Fixed bid price: 250 cents
• Billing code: DEMO-BILL-001
• 10 minutes expiration time
• No database modifications
• Both options return identical demo responses

This endpoint allows you to request a real-time offer for a specific screen. The matching engine will evaluate all eligible advertisements and return the best match based on your criteria.

Optional parameters

Name
min_bid_cents
Type
integer
Description
Minimum bid amount in cents to consider for offers.
Name
demo
Type
boolean
Description
Set to true to get demo responses for testing. Can be used with any Screen-ID.
Name
vast
Type
boolean
Description
Set to true to include VAST XML in the response for programmatic advertising integrations. The VAST XML follows the VAST 4.0 standard and includes tracking events and advertisement metadata.

Request

GET

/functions/v1/api/offers/request/[screenId]

curl -X GET "https://api.adlocaite.com/functions/v1/api/offers/request/[screenId]?min_bid_cents=200" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "offer_id": "32c7c9b5-8b2a-4cac-b298-146320100325",
  "bid_price_cents": 253,
  "asset_url": "https://cdn.example.com/assets/ad_image_1920x1080.jpg",
  "expires_at": "2025-08-19 14:49:52.874089+00",
  "billing_code": "ORG001-PUB-2024"
}

Demo Response

{
  "offer_id": "test-offer-test",
  "bid_price_cents": 250,
  "asset_url": "https://via.placeholder.com/1920x1080",
  "expires_at": "2025-08-27 14:10:00.000000+00",
  "billing_code": "DEMO-BILL-001"
}

Response with VAST XML

{
  "offer_id": "32c7c9b5-8b2a-4cac-b298-146320100325",
  "bid_price_cents": 253,
  "asset_url": "https://cdn.example.com/assets/ad_image_1920x1080.jpg",
  "expires_at": "2025-08-19 14:49:52.874089+00",
  "billing_code": "ORG001-PUB-2024",
  "vast": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<VAST version=\"4.0\" xmlns=\"http://www.iab.com/VAST\">\n  <Ad id=\"32c7c9b5-8b2a-4cac-b298-146320100325\">\n    <InLine>\n      <AdSystem version=\"1.0\">Adlocaite</AdSystem>\n      <AdTitle><![CDATA[Digital Out-of-Home Advertisement]]></AdTitle>\n      <Advertiser><![CDATA[Advertiser]]></Advertiser>\n      <Expires>2025-08-19 14:49:52.874089+00</Expires>\n      <Creatives>\n        <Creative id=\"32c7c9b5-8b2a-4cac-b298-146320100325_creative\" sequence=\"1\">\n          <Linear>\n            <MediaFiles>\n              <MediaFile id=\"32c7c9b5-8b2a-4cac-b298-146320100325_media\" delivery=\"progressive\" type=\"image/jpeg\" scalable=\"true\" maintainAspectRatio=\"true\">\n                <![CDATA[https://cdn.example.com/assets/ad_image_1920x1080.jpg]]>\n              </MediaFile>\n            </MediaFiles>\n            <TrackingEvents>\n              <Tracking event=\"complete\">\n                <![CDATA[https://tracking.adlocaite.com/track?offer_id=32c7c9b5-8b2a-4cac-b298-146320100325&event=complete&timestamp=1729426192874]]>\n              </Tracking>\n            </TrackingEvents>\n          </Linear>\n        </Creative>\n      </Creatives>\n      <Extensions>\n        <Extension type=\"adlocaite\">\n          <AdlocaiteData>\n            <OfferId>32c7c9b5-8b2a-4cac-b298-146320100325</OfferId>\n            <BidPriceCents>253</BidPriceCents>\n            <BillingCode>ORG001-PUB-2024</BillingCode>\n          </AdlocaiteData>\n        </Extension>\n      </Extensions>\n    </InLine>\n  </Ad>\n</VAST>"
}

Error Response (422)

{
  "error": "No matches meet minimum bid requirement",
  "status": 422
}

Error Response (404)

{
  "error": "No matches available",
  "status": 404
}

Using External ID

Performance Warning

External IDs significantly reduce API performance. Only use this endpoint if your CMS or playout system cannot work with UUIDs. Your account must be activated for external IDs - contact support@adlocaite.com.

This endpoint returns the same offer data as the UUID version, but allows you to identify screens using your own external identifiers. Use only if UUIDs are not technically feasible in your system.

Path parameters

Name
externalId
Type
string
Description
Your custom identifier for the screen (e.g., "SCREEN-001", "berlin-hauptbahnhof").

Query parameters

Name
min_bid_cents
Type
integer
Description
Optional minimum bid amount in cents to consider for offers.
Name
demo
Type
boolean
Description
Set to true to get demo responses for testing. Can be used with any external ID.
Name
vast
Type
boolean
Description
Set to true to include VAST XML in the response for programmatic advertising integrations. The VAST XML follows the VAST 4.0 standard and includes tracking events and advertisement metadata.

Request

GET

/functions/v1/api/offers/request/external-id/[externalId]

curl -X GET "https://uamoseamohhsxwybytqx.supabase.co/functions/v1/api/offers/request/external-id/SCREEN-001?min_bid_cents=150" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "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"
}

Error Response (404)

{
  "error": "Screen not found with external_id: SCREEN-001"
}

Error Response (422)

{
  "error": "No matches meet minimum bid requirement",
  "status": 422
}

POST/functions/v1/api/offers/response/[offerId]

Respond to an offer

Demo/Test Functionality

Use offer ID test-offer-test for testing and development.

• Accepts both Accept and Reject actions
• Returns demo deal_id and billing_id for Accept
• Confirms rejection for Reject actions
• No database modifications

This endpoint allows you to accept or reject an offer. Once you respond, the offer becomes invalid and cannot be changed.

Required attributes

Name
action
Type
string
Description
The response to the offer. Must be either accept or reject.
Name
accepted_price_cents
Type
integer
Description
Required when action is accept. The accepted price in cents (must be positive).

Optional attributes

Name
rejection_reason
Type
string
Description
Optional when action is reject. Reason for rejecting the offer.

Request

POST

/functions/v1/api/offers/response/[offerId]

curl -X POST https://api.adlocaite.com/functions/v1/api/offers/response/[offerId] \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "accept",
    "accepted_price_cents": 200
  }'

Response (Accept)

{
  "success": true,
  "action": "accepted",
  "deal_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "billing_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "price_cents": 200,
  "message": "Offer accepted, deal created, and commission billed",
  "billing_code": "123456789"
}

Response (Reject)

{
  "success": true,
  "action": "rejected",
  "message": "Offer rejected and removed",
  "rejection_reason": "Not suitable for our audience",
  "billing_code": "123456789"
}

Demo Response (Accept)

{
  "success": true,
  "action": "accepted",
  "deal_id": "demo-deal-12345",
  "billing_id": "demo-billing-67890",
  "price_cents": 250,
  "message": "Demo offer accepted successfully",
  "billing_code": "DEMO-BILL-001"
}

Demo Response (Reject)

{
  "success": true,
  "action": "rejected",
  "message": "Demo offer rejected successfully",
  "rejection_reason": "Demo rejection",
  "billing_code": "DEMO-BILL-001"
}

Error Response (400)

{
  "error": "Action must be \"accept\" or \"reject\""
}

Error Response (400)

{
  "error": "Accepted price must be provided"
}

Error Response (401)

{
  "error": "Invalid or expired API key"
}

Error Response (404)

{
  "error": "Offer not found, expired, or access denied"
}

Error Response (500)

{
  "error": "Failed to process offer"
}

Deal confirmation

When you accept an offer, it becomes a confirmed deal. The deal contains all the information needed to display the advertisement, including the asset URL and exact timing requirements.

Deal properties

Name
deal_id
Type
string
Description
Unique identifier for the confirmed deal.
Name
action
Type
string
Description
Action taken - will be accepted for accepted offers.
Name
message
Type
string
Description
Confirmation message about the deal.
Name
success
Type
boolean
Description
Whether the action was successful.
Name
billing_id
Type
string
Description
Unique identifier for the billing record.
Name
price_cents
Type
integer
Description
Your revenue from this deal in cents.
Name
billing_code
Type
string | null
Description
Billing code for the organization-publisher combination. Enables publisher-specific billing identification.