Overview

The Sandbox API consists of pre-defined responses that allow you to interact with and test your offer content prior to going into production. The Sandbox API serves as a modified version of the production environment in your development workflow. The ads you create in this environment do not actually serve.

Base URL:

https://pub-api-us.sandbox.cardlytics.com/v2/

Documentation Reference:

For further details, please refer to the official documentation: Cardlytics Ads v2 API Documentation

Endpoints

1. Start Session - Institution Scope

Initiates a session with institution-level access.

• Method: POST
• URL: /session/startSession
• Body (JSON):
  JSON

  { "scopes": ["api:institution"] }
  

• Example:
  Bash

  curl -X POST https://pub-api-us.sandbox.cardlytics.com/v2/session/startSession \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["api:institution"] }'
  

---

2. Start Session - Customer Scope

Starts a session with customer-level access.

• Method: POST
• URL: /session/startSession
• Body (JSON):
  JSON

  {
    "sourceCustomerId": "3c8319ef-9a48-43f6-a3b9-81bd8922532f",
    "scopes": ["api:customer"]
  }
  

---

3. Get Customer Profile

Retrieves a customer profile based on session token.

• Method: GET
• URL: /customerProfile/getCustomerProfile
• Headers: X-CDLX-Session-Token
• Token Scope: Customer
• Body (JSON):
  JSON

  {
    "sourceCustomerId": "1110120-BT41",
    "scopes": ["api:customer"]
  }
  

---

4. Get Customer Ad Redemptions

Fetches ad redemptions for a customer.

• Method: GET
• URL: /customerProfile/getCustomerAdRedemptions
• Headers: X-CDLX-Session-Token
• Token Scope: Customer

---

5. Get Customer Reward Summary

Returns a summary of customer rewards.

• Method: GET
• URL: /customerProfile/getCustomerRewardSummary
• Headers: X-CDLX-Session-Token
• Token Scope: Customer

---

6. Create Customers

Allows for creating multiple customers within the system.

• Method: POST
• URL: /data/customers
• Token Scope: Institution
• Body (JSON):
  JSON

  {
    "customers": [
      {
        "sourceCustomerId": "afa2r21-25f9-4501-b9db-e78afa73c0e3",
        "sourceParentCustomerId": "2e052a88-6ae1-4501-b9db-e78afa73c0e3",
        ...
      }
    ]
  }
  

---

7. Update Customer

Updates customer information.

• Method: PUT
• URL: /data/customers
• Token Scope: Institution
• Body (JSON):
  JSON

  {
    "customers": [
      {
        "sourceCustomerId": "afa2r21-25f9-4501-b9db-e78afa73c0e3",
        ...
      }
    ]
  }
  

---

8. Create Transactions

Creates multiple transactions for a customer.

• Method: POST
• URL: /data/transactions
• Token Scope: Institution
• Body (JSON):
  JSON

  {
    "transactions": [
      {
        "transactionId": "8179bea8-0d04-4d2b-bd78-b1ffbad3ec48",
        ...
      }
    ]
  }
  

---

9. Update Accounts

Updates account details for a customer.

• Method: PUT
• URL: /data/accounts
• Token Scope: Institution
• Body (JSON):
  JSON

  {
    "accounts": [
      {
        "sourceAccountId": "42c57311-25f9-4501-b9db-e78afa73c0e3",
        ...
      }
    ]
  }
  

---

10. Create Customer Event

Creates an event for a customer.

• Method: POST
• URL: /events/clientEvent
• Token Scope: Customer
• Body (JSON):
  JSON

  {
    "clientEvents": [
      {
        "clientEventId": "dde3b802-10fb-11ee-be56-0242ac120002",
        ...
      }
    ]
  }
  

---

11. Get Ads

This endpoint retrieves ads for a customer based on the specified channel, sections, visibility states, and location.

• Method: POST
• URL: /ads/getAds
• Token Scope: Customer
• Headers:
  • X-CDLX-Session-Token: Session token obtained after starting a session
  • Content-Type: application/json
• Body (JSON):
  JSON

  {
      "channel": "Email",
      "sections": ["Landing", "Summary"],
      "maxAdLimit": 50,
      "visibilityStates": ["VISIBLE"],
      "customerLocation": {
          "latitude": "37.7000",
          "longitude": "122.4000"
      }
  }