Brand Metrics and Management API Documentation

Access affiliate performance data from your Inflektion account and enroll new affiliates programmatically. Pull summary reports, conversion-level logs, and affiliate details, and create affiliates directly in your program.

Overview

The Brand Metrics API gives brands programmatic access to the affiliate performance data flowing through Inflektion. It is organized around REST principles and uses standard HTTP verbs, status codes, and JSON request/response bodies.

The API is organized into the following capabilities:

• Summary Reporting: Aggregate metrics grouped by affiliate, date, geography, or other dimensions. Ideal for leaderboards and time-series charts.
• Conversion Log: Transaction-level detail for every conversion and (optionally) on-site event. Ideal for daily syncs into a data warehouse or BI tool.
• Edit Conversion: Update the sale amount on an existing conversion. Revenue and payout are adjusted automatically when applicable.
• Delete Conversion: Remove a conversion from the record.
• Affiliate Details: Active affiliate roster with contract tier, join date, and referral tree data.
• Single Affiliate Details: The same affiliate record, looked up by affiliate ID and returned as a single object.
• Create Affiliate: Enroll a new affiliate directly into your program under a specific offer.
• Check Vanity Slug Availability: Pre-check whether a vanity URL slug is available before creating an affiliate.
• Region Lookup: Valid region_code values for a given country, for use in Create Affiliate.
• Country Lookup: Valid country_code values, for use in Create Affiliate.
• Timezone Lookup: The full reference list of supported timezone IDs.

Authentication

All requests must be authenticated with a Bearer token in the Authorization header. Your API key is provided by your Inflektion account manager if you're on the Growth or Enterprise plans.

Authorization: Bearer YOUR_API_KEY

Base URL

All requests are made over HTTPS to https://brand-api.inflektion.io

Request bodies (where applicable) must be JSON with the "Content-Type" header set to "application/json".

Pagination

Endpoints that return lists include a "paging" object in the response body:

{
  "paging": {
    "page": 2,
    "page_size": 50,
    "total_count": 150
  }
}

Pages are 1-indexed (the first page is 1, not 0). When no pagination parameters are specified, the API returns the first page with a default page_size of 50. The maximum page size is 2000 unless an endpoint specifies otherwise.

To request a specific page, include page and page_size as query string parameters on GET endpoints, or as fields in the JSON body on POST endpoints.

Timezones

Every reporting request must include a timezone_id to anchor date ranges correctly. Common timezone IDs:

For the full reference list, see the Timezone Lookup section below. If you need a timezone ID that is not listed there, contact your Inflektion account manager.

Summary Reporting

POST /api/reporting/entity

Returns aggregate performance metrics grouped by one or more dimensions, similar to a pivot table. Use this endpoint to build leaderboards, time-series charts, or summary dashboards.

Request Body

Available Columns

Response Structure

The response contains three objects:

summary: Aggregate metrics for the entire date range across all groupings.

performance: Time-series data for building aggregate charts. The granularity adapts to the date range automatically:

• 1 day — 96 intervals of 15 minutes
• 2–3 days — 1-hour intervals
• 4–7 days — 6-hour intervals
• 8–14 days — 12-hour intervals
• >14 days — Daily intervals

table: Aggregate metrics broken down by the requested grouping column(s). Limited to 10,000 rows. Ideal for leaderboard/dashboard views.

Example Request

View aggregate data, grouped by affiliate_id, for the months of August through November 2025.

curl --request POST 'https://brand-api.inflektion.io/api/reporting/entity' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "from": "2025-08-01",
    "to": "2025-11-30",
    "timezone_id": 90,
    "currency_id": "USD",
    "query": {
      "filters": [],
      "search_terms": []
    },
    "columns": [
      { "column": "affiliate_id" }
    ]
  }'

Conversion Log

POST /api/reporting/conversions

Returns transaction-level data for individual conversions and (optionally) on-site events such as Add to Cart. Results are paginated.

Request Body

Example Request

curl --request POST 'https://brand-api.inflektion.io/api/reporting/conversions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "show_conversions": true,
    "show_events": false,
    "show_only_vt": false,
    "show_only_ct": false,
    "from": "2025-11-30",
    "to": "2025-11-30",
    "timezone_id": 90,
    "currency_id": "USD",
    "query": {
      "filters": [],
      "search_terms": []
    }
  }'

Example Response

{
  "conversions": [
    {
      "conversion_id": "9008277d544441a7bc0c64533ccbbad8",
      "conversion_unix_timestamp": 1764489640,
      "cost_type": "RPS",
      "cost": 8.09,
      "session_user_ip": "203.0.113.42",
      "conversion_user_ip": "203.0.113.42",
      "country": "United States",
      "region": "California",
      "city": "Los Angeles",
      "dma": 0,
      "carrier": "",
      "platform": "iOS",
      "os_version": "",
      "device_type": "Phone",
      "brand": "Apple",
      "browser": "Safari",
      "language": "en",
      "http_user_agent": "Mozilla/5.0 ...",
      "is_event": false,
      "transaction_id": "41c9b30abde3434db512025fab386952",
      "click_unix_timestamp": 1764489486,
      "event": "Purchase",
      "currency_id": "USD",
      "isp": "",
      "adv1": "",
      "adv2": "",
      "adv3": "",
      "adv4": "couponcode",
      "adv5": "",
      "sale_amount": 53.91,
      "relationship": {
        "offer": {
          "network_offer_id": 123,
          "network_id": 888,
          "name": "Your Brand",
          "offer_status": "active"
        },
        "events_count": 0,
        "affiliate_id": 123456,
        "affiliate": {
          "network_affiliate_id": 123456,
          "network_id": 888,
          "name": "Sample Affiliate",
          "account_status": "active"
        },
        "sub1": "",
        "sub2": "",
        "sub3": "",
        "sub4": "",
        "sub5": "",
        "source_id": "",
        "offer_url": null
      },
      "coupon_code": "brand-affiliate"
    }
  ],
  "paging": {
    "page": 1,
    "page_size": 50,
    "total_count": 271
  }
}

Suggested Fields to Log

When ingesting Conversion Log data into your own systems, we recommend storing at minimum the following fields:

Edit Conversion

PUT /api/reporting/conversions/{conversion_id}/saleamount

Updates the sale amount on an existing conversion. Revenue and payout are adjusted automatically when applicable.

Query Parameters

Request Body

Example Request

curl --location --request PUT 'https://brand-api.inflektion.io/api/reporting/conversions/{conversion_id}/saleamount' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "sale_amount": 199.00
  }'

Delete Conversion

DELETE /api/reporting/conversions/{conversion_id}

Deletes a conversion from the record.

Query Parameters

Example Request

curl --location --request DELETE 'https://brand-api.inflektion.io/api/reporting/conversions/{conversion_id}' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Affiliate Details

GET /api/affiliates?page={page}&page_size={page_size}

Returns a paginated list of all active affiliates in your program, including their contract tier, join date, and referral chain.

Query Parameters

Response Fields

Example Request

curl --request GET 'https://brand-api.inflektion.io/api/affiliates?page=1&page_size=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
    "affiliates": [
        {
            "network_affiliate_id": 17759,
            "name": "Biohacker Bob",
            "emails": [
                "bob@superpopgummies.com",
                "anotheremail@sugarpopgummies.com"
            ],
            "time_created": 1749178472,
            "time_loggedin": 1776422397,
            "contract_name": "15% Revshare",
            "type": "Affiliate",
            "referrer_id": null,
            "primary_url": "https://sugarpopgummies.com/biohackerbob",
            "primary_qr": "https://assets.inflektion.ai/qr/https%3A%2F%2Fsugarpopgummies.com%2Fbiohackerbob",
            "primary_url_direct": null,
            "primary_code": "BIOHACKERBOB",
            "payment_added": true,
            "personalization_added": true
        },
        {
            "network_affiliate_id": 17760,
            "name": "FitJess 50+",
            "emails": [
                "jess@superpopgummies.com"
            ],
            "time_created": 1749179125,
            "time_loggedin": 1768488140,
            "contract_name": "15% Revshare",
            "type": "Influencer",
            "referrer_id": 17759,
            "primary_url": "https://sugarpopgummies.com/fitjess",
            "primary_qr": "https://assets.inflektion.ai/qr/https%3A%2F%2Fsugarpopgummies.com%2Ffitjess",
            "primary_url_direct": null,
            "primary_code": "FITJESS",
            "payment_added": false,
            "personalization_added": false
        }
    ],
    "paging": {
        "page": 1,
        "page_size": 1000,
        "total_count": 5
    }
}

Single Affiliate Details

GET /api/affiliates/{affiliate_id}

Returns the details for one affiliate, looked up by their affiliate ID. This is the single-record version of the Affiliate Details endpoint: the response is a single affiliate object rather than an array, and no "paging" object is returned.

Query Parameters

Response Fields

The response returns the same fields as the Affiliate Details endpoint above, for a single affiliate:

Example Request

curl --location 'https://brand-api.inflektion.io/api/affiliates/17759' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
    "network_affiliate_id": 17759,
    "name": "Biohacker Bob",
    "emails": [
        "bob@superpopgummies.com",
        "anotheremail@sugarpopgummies.com"
    ],
    "time_created": 1749178472,
    "time_loggedin": 1776422397,
    "contract_name": "15% Revshare",
    "type": "Affiliate",
    "referrer_id": null,
    "primary_url": "https://sugarpopgummies.com/biohackerbob",
    "primary_qr": "https://assets.inflektion.ai/qr/https%3A%2F%2Fsugarpopgummies.com%2Fbiohackerbob",
    "primary_url_direct": null,
    "primary_code": "BIOHACKERBOB",
    "payment_added": true,
    "personalization_added": true
}

Create Affiliate

POST /api/affiliates

Enrolls a new affiliate directly into your program under a specific offer. All validation runs before anything is created: a vanity slug, coupon code, or storefront redirect that is already taken fails immediately with no side effects.

IMPORTANT: The offer_uuid identifies which of your offers/brands the affiliate is being created for. This is provided to you directly by your Inflektion account manager — there is no endpoint to look it up yourself.

Request Body

Channel Object

Each entry in channels is an object with a type and a handle:

{ "type": "instagram", "handle": "@youraffiliate" }

Example Request

curl --request POST 'https://brand-api.inflektion.io/api/affiliates' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "offer_uuid": "11111111-1111-1111-1111-111111111111",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "country_code": "US",
    "region_code": "CA",
    "address_1": "123 Main St",
    "city": "Springfield",
    "zip_postal_code": "12345",
    "cell_phone": "5551234567",
    "vanity_slug": "adalovelace",
    "channels": [
      { "type": "instagram", "handle": "@ada" }
    ]
  }'

Example Response

{
  "network_affiliate_id": 45566,
  "status": "pending"
}

status is either "pending" (awaiting manual review/approval) or "approved" (when auto_approve was set to true).

VALIDATION: If the vanity slug, coupon code, or a required field is invalid, the request fails with a 422 and no affiliate is created. Nothing is left partially created. See the Error Handling section below.

Check Vanity Slug Availability

POST /api/affiliates/vanity-slug-check

Pre-checks whether a vanity URL slug is available for a given offer, both within Inflektion and against your program's live coupon codes, before you submit the full Create Affiliate payload.

Request Body

Example Request

curl --request POST 'https://brand-api.inflektion.io/api/affiliates/vanity-slug-check' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "offer_uuid": "11111111-1111-1111-1111-111111111111",
    "slug": "adalovelace"
  }'

Example Response

{
  "available": true
}

available is true, false, or null. A null value means the availability check could not be completed at that moment, and is returned with a 502 status and a message field. Treat it as "unknown" rather than "available", and retry.

NOTE: This is a best-effort pre-check, not a guarantee. The Create Affiliate endpoint above still runs its own full validation at creation time and is the authoritative gate.

Region Lookup

GET /api/regions?country_code={country_code}

Returns the valid region_code values for a given country, for use in the Create Affiliate endpoint's region_code field.

Query Parameters

Example Request

curl --request GET 'https://brand-api.inflektion.io/api/regions?country_code=US' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "regions": [
    { "region_code": "CA", "region_name": "California", "country_code": "US" },
    { "region_code": "NY", "region_name": "New York", "country_code": "US" }
  ]
}

Country Lookup

GET /api/countries

Returns the full list of valid country_code values, for use in the Create Affiliate endpoint's country_code field.

Example Request

curl --request GET 'https://brand-api.inflektion.io/api/countries' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "countries": [
    { "country_code": "US", "country_name": "United States" },
    { "country_code": "CA", "country_name": "Canada" }
  ]
}

Timezone Lookup

GET /api/timezones

Returns the full timezone reference list, including every timezone_id accepted by the reporting endpoints. 

Example Request

curl --request GET 'https://brand-api.inflektion.io/api/timezones' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "timezones": [
    { "timezone_id": 80, "timezone_name": "Eastern Daylight Time (America/New_York)", "timezone": "America/New_York", "utc_offset": "-04:00" },
    { "timezone_id": 90, "timezone_name": "Pacific Daylight Time (America/Los_Angeles)", "timezone": "America/Los_Angeles", "utc_offset": "-07:00" }
  ]
}

Error Handling

Each of the API points use standard HTTP status codes. Errors return a JSON body with a descriptive message.

Rate Limits

API requests are rate-limited per API key. The affiliate-creation endpoints (Create Affiliate, Check Vanity Slug Availability, and the Region, Country, and Timezone Lookup endpoints) allow 60 requests per minute. If you receive a 429 response, implement an exponential backoff strategy before retrying. For high-volume integrations or real-time use cases, contact your Inflektion account manager to discuss elevated rate limits.

Need help?

Reach out to your Inflektion account manager through Slack or email.