OData API - Fetching Promotional Offers

Overview

The OData API allows you to fetch promotional offers to display to customers. This is the primary endpoint for real-time offer retrieval.

Endpoint

GET https://pr-api.falconlabs.us/api/odata

Authentication

Use the publisher’s Public Key:

Authorization: Bearer PUBLIC_KEY

Note: This is the only endpoint that uses the public key. All other endpoints use the private key.

Query Parameters

Required Parameters

• placementId (string): Placement ID from placement creation
• sessionId (string): Unique session identifier for the customer (can use email, hashed email, or orderId)
• at.email (string): Customer email address (plain or SHA-256 hashed)
• at.orderid (string): Order ID

Note: At minimum, you must provide placementId, sessionId, and either at.email or at.orderid for proper tracking.

Optional Parameters

• count (number, default: 4): Number of offers to return

Customer Data Parameters

Pass customer and order data with the at. prefix for better targeting and analytics:

Customer Information:

• at.email (string): Customer email address (lowercase, trimmed, or SHA-256 hashed)
• at.firstname or at.fname (string): Customer first name
• at.lastname or at.lname (string): Customer last name
• at.phone or at.mobile (string): Phone number (10-15 digits)
• at.country (string): Country code (ISO format, e.g., “US”, “GB”)
• at.language (string): Language code (e.g., “en”, “es”)
• at.address (string): Customer address (max 500 chars)
• at.zipcode (string): ZIP/postal code (max 20 chars)

Email Hashing: For privacy compliance, you can hash the email using SHA-256 before sending. Pass the hashed value in at.email parameter. Only SHA-256 hashing is supported.

Example: email@example.com → SHA-256 → a1b2c3d4e5f6... (64-character hex string)

Order Information:

• at.orderid or at.order_id (string): Order ID (max 100 chars)
• at.amount or at.ordervalue (number): Order amount (0-1,000,000)
• at.currency (string): Currency code (e.g., “USD”, “EUR”, “GBP”)
• at.billingaddress1 (string): Billing address (max 500 chars)
• at.billingzipcode (string): Billing ZIP code (max 20 chars)
• at.paymenttype or at.payment_type (string): Payment method
• Valid values: creditCard, debitCard, paypal, applePay, googlePay, bankTransfer, crypto, other

Supported Currencies: USD, EUR, GBP, CAD, AUD, JPY, CNY, NZD, CHF, SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN, HRK, RUB, TRY, BRL, MXN, ARS, CLP, COP, PEN, UYU, INR, IDR, MYR, PHP, SGD, THB, VND, KRW, HKD, TWD, SAR, AED, ILS, EGP, ZAR, NGN, KES, GHS

Example Request

curl -X GET "https://pr-api.falconlabs.us/api/odata?placementId=clx4d5e6f7g8h9i0j1k2l3m4n&sessionId=session_abc123&count=4&at.email=customer@example.com&at.firstname=John&at.lastname=Doe&at.orderid=ORDER-12345&at.amount=125.50&at.currency=USD&at.country=US" \
  -H "Authorization: Bearer pub_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Success Response (200 OK)

{
  "offers": [
    {
      "bannerId": "12345",
      "title": "15% off your next order",
      "header": "Limited-time thank you",
      "description": "Save on your next purchase.\nUse code THANKS15",
      "ctaText": "REDEEM",
      "declineButtonText": "No thanks",
      "clickUrl": "https://pr-api.falconlabs.us/click?...",
      "beaconUrl": "https://pr-api.falconlabs.us/vdata?...",
      "closeUrl": "https://pr-api.falconlabs.us/close?...",
      "termsUrl": "https://brand.com/terms",
      "icon": {
        "url": "https://cdn.example.com/icon.png",
        "width": 120,
        "height": 120
      }
    },
    {
      "bannerId": "12346",
      "title": "Get 20% off at Nike",
      "header": "Shop athletic wear",
      "description": "Premium sportswear at great prices",
      "ctaText": "SHOP NOW",
      "declineButtonText": "No thanks",
      "clickUrl": "https://pr-api.falconlabs.us/click?...",
      "beaconUrl": "https://pr-api.falconlabs.us/vdata?...",
      "closeUrl": "https://pr-api.falconlabs.us/close?..."
    }
  ],
  "adDisplayDelay": 0,
  "isTestMode": true,
  "siteStatus": "active",
  "templateData": {
    "brandName": "Fashion Boutique",
    "privacyUrl": "https://fashionboutique.com/privacy",
    "brandTemplateImageUrl": "https://cdn.example.com/brand-logo.png",
    "toggleCloseButtonDelay": 5000,
    "showFirstOfferIcon": true,
    "showPartnership": true,
    "templateConfig": {
      "iconConfig": {
        "mobilePosition": "below-subtitle-above-description",
        "showIcon": true
      },
      "textConfig": {
        "titleSize": "large",
        "subtitleSize": "medium",
        "descriptionSize": "medium",
        "titleTransform": "uppercase"
      },
      "layoutConfig": {
        "gridColumnsDesktop": ["60%", "fill"],
        "gridColumnsMobile": "100%",
        "gridGap": "large"
      },
      "buttonConfig": {
        "primaryButtonKind": "primary",
        "primaryButtonAppearance": "accent",
        "buttonLayoutMobile": "vertical"
      },
      "linksConfig": {
        "showTermsLink": true,
        "showDisclaimerLink": false
      },
      "footerConfig": {
        "showPartnership": true,
        "privacyLinkLabel": "Privacy Policy"
      }
    }
  }
}

Response Fields:

• offers: Array of promotional offers to display
  • clickUrl: URL to redirect to when customer clicks the offer
  • beaconUrl: URL to call when offer is displayed (impression tracking)
  • closeUrl: URL to call when customer closes the ad
• isTestMode: Whether the placement is in test mode
• templateData: Configuration data for customizing the ad display
  • templateConfig: Display configuration parameters (see Adjustable Template section)

Error Responses

400 Bad Request - Missing Parameters

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Missing required parameters",
    "details": {
      "missingFields": ["placementId", "sessionId"]
    }
  }
}

401 Unauthorized - Invalid Public Key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing public key"
  }
}

404 Not Found - Invalid Placement

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Placement not found",
    "details": {
      "placementId": "invalid_placement_id"
    }
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred while fetching offers"
  }
}