Quickstart

This guide will get you up and running with the Adlocaite API in just a few minutes. We'll show you how to make your first offer request and handle responses using cURL. You'll also see examples of how to call these same endpoints from popular programming languages.

Using cURL

The Adlocaite API is designed to work perfectly with cURL. Most systems have cURL pre-installed, making it the fastest way to get started:

curl --version

Making your first offer request

Let's request an offer for one of your screens. Replace [screenId] with your actual screen ID and YOUR_API_KEY with your API key:

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

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

No offers available:

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

Accepting an offer

If you received an offer, you can accept it. Remember that offers expire quickly, so respond promptly:

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": 253
  }'

Accept response:

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

Rejecting an offer

Sometimes you might want to reject an offer. You can provide an optional rejection reason:

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": "reject",
    "rejection_reason": "Not suitable for our audience"
  }'

Reject response:

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

Pre-caching assets (Optional)

For better performance, you can pre-cache assets for your screens:

curl -X GET "https://api.adlocaite.com/functions/v1/api/screens/[screenId]/cacheable-assets?min_bid_cents=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

What's next?

Great! You've successfully made your first offer request and learned how to respond to offers. Here are some helpful next steps:

• Learn about authentication and API keys
• Explore all available endpoints
• Understand error handling
• Check out the FAQ for common questions

Integration checklist