Developer Docs

API Reference

Create tracking links, manage creators, and pull analytics programmatically using your workspace API key.

API access requires a paid plan (Starter, Growth, or Agency).

Authentication

The public REST endpoints documented below use your workspace API key, passed in the x-api-key header. Dashboard-only products and offers, tracking checks, funnels, and insights use your signed-in workspace session instead.

Find your API key in Dashboard → Settings.

Example request

curl https://www.attriq.io/api/v1/stats \
  -H "x-api-key: YOUR_API_KEY"

Keep your API key secret. Do not expose it in client-side code, public repositories, or browser requests. Use it only from your server.

Base URL

https://www.attriq.io/api/v1

Plan Requirements

API access is available on paid plans only:

Plan	API Access	Creators	Links	Clicks/mo
Free	No	3	10	1,000
Starter ($29/mo)	Yes	10	50	10,000
Growth ($79/mo)	Yes	Unlimited	500	100,000
Agency ($199/mo)	Yes	Unlimited	5,000	500,000

Links

GET

/api/v1/links

List all tracking links in your workspace

Query Parameters

Parameter	Type	Required	Description
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Items per page, max 100 (default: 50)
`status`	string	Optional	"active" or "inactive"
`creator_id`	uuid	Optional	Filter by creator ID

Example

curl https://www.attriq.io/api/v1/links?status=active&limit=10 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "uuid",
      "slug": "abc123xy",
      "tracking_url": "https://www.attriq.io/l/abc123xy",
      "destination_url": "https://yourbrand.com/product",
      "utm_source": "influencer",
      "utm_medium": "sarah_jones",
      "utm_campaign": "summer_launch",
      "is_active": true,
      "group_id": null,
      "creator": {
        "id": "uuid",
        "name": "Sarah Jones",
        "platform": "youtube"
      },
      "created_at": "2025-07-14T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "total_pages": 5
  }
}

POST

/api/v1/links

Create a new tracking link

Request Body (JSON)

Parameter	Type	Required	Description
`destination_url`	string	Required	The URL the link redirects to
`creator_id`	uuid	Optional	Optional creator association. Omit for campaigns without a creator.
`utm_campaign`	string	Optional	Campaign name for UTM tagging
`marketing_source`	string	Optional	creator, social, email, paid_ad, affiliate, qr, or custom. Defaults to creator with a creator_id, otherwise social.
`source_label`	string	Optional	Required for a custom source (max 100 characters).
`goal_type`	string	Optional	purchase (default), signup, lead, or custom.
`goal_name`	string	Optional	Required event name for a custom goal (max 100 characters). Match this name exactly when reporting the event.
`spend`	number	Optional	Nonnegative manual all-time spend for this link, with at most two decimal places. Default 0; separate from creator fees.
`spend_currency`	string	Optional	Three-letter spend currency code. Default USD.
`slug`	string	Optional	Custom slug (3-32 chars, lowercase alphanumeric/hyphens). Auto-generated if omitted.

Example

curl -X POST https://www.attriq.io/api/v1/links \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://yourbrand.com/summer-sale",
    "creator_id": "creator-uuid-here",
    "utm_campaign": "summer_launch",
    "slug": "sarah-summer"
  }'

Response (201)

{
  "data": {
    "id": "uuid",
    "slug": "sarah-summer",
    "tracking_url": "https://www.attriq.io/l/sarah-summer",
    "destination_url": "https://yourbrand.com/summer-sale",
    "utm_source": "influencer",
    "utm_medium": "sarah_jones",
    "utm_campaign": "summer_launch",
    "is_active": true,
    "creator": {
      "id": "creator-uuid",
      "name": "Sarah Jones"
    },
    "created_at": "2025-07-14T12:00:00Z"
  }
}

Email campaign with a signup goal (no creator required)

curl -X POST https://www.attriq.io/api/v1/links \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://yourbrand.com/trial",
    "marketing_source": "email",
    "utm_campaign": "product_launch",
    "goal_type": "signup",
    "spend": 150,
    "spend_currency": "USD"
  }'

Source, goal and spend fields are included in link responses. The Campaigns dashboard groups all-time results by source, campaign and link, and keeps currencies separate. Creator fees remain in creator reporting; do not repeat a whole campaign budget on every link.

Link Stats

GET

/api/v1/links/:linkId/stats

Get click & conversion stats for a specific link

Conversions and revenue now use valid attribution to this link, not all sales by its creator. total_conversions counts purchases; goal_completions counts the link's configured goal. revenue_by_currency keeps every currency separate, while total_revenue uses the selected currency.

Query Parameters

Parameter	Type	Required	Description
`days`	integer	Optional	Lookback period in days, max 90 (default: 30)
`currency`	string	Optional	Three-letter currency for total_revenue; defaults to the link's spend currency.

Example

curl https://www.attriq.io/api/v1/links/LINK_ID/stats?days=7 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": {
    "link": {
      "id": "uuid",
      "slug": "sarah-summer",
      "tracking_url": "https://www.attriq.io/l/sarah-summer",
      "destination_url": "https://yourbrand.com/summer-sale",
      "is_active": true,
      "created_at": "2025-07-14T12:00:00Z",
      "creator": {
        "id": "uuid",
        "name": "Sarah Jones",
        "platform": "youtube"
      }
    },
    "stats": {
      "period_days": 7,
      "total_clicks": 1284,
      "unique_clicks": 1050,
      "bot_clicks": 42,
      "suspicious_clicks": 8,
      "total_conversions": 23,
      "total_revenue": 2847.50,
      "conversion_rate": 2.19
    }
  }
}

Creators

GET

/api/v1/creators

List all creators in your workspace

Query Parameters

Parameter	Type	Required	Description
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Items per page, max 100 (default: 50)
`include_stats`	boolean	Optional	Set to "true" to include click/conversion/revenue stats per creator

Example with stats

curl "https://www.attriq.io/api/v1/creators?include_stats=true" \
  -H "x-api-key: YOUR_API_KEY"

Response (with include_stats=true)

{
  "data": [
    {
      "id": "uuid",
      "name": "Sarah Jones",
      "platform": "youtube",
      "compensation_type": "flat_fee",
      "flat_fee": 500,
      "total_clicks": 3200,
      "unique_clicks": 2800,
      "total_conversions": 45,
      "total_revenue": 5670.00,
      "total_cost": 500,
      "net_profit": 5170.00,
      "roas": 11.34,
      "conversion_rate": 1.61
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 5, "total_pages": 1 }
}

POST

/api/v1/creators

Create a new creator

Request Body (JSON)

Parameter	Type	Required	Description
`name`	string	Required	Creator's display name
`email`	string	Optional	Creator's email address
`platform`	string	Optional	"youtube", "tiktok", "instagram", "twitter", or "other" (default: "other")
`flat_fee`	number	Optional	Flat fee amount (default: 0)
`coupon_code`	string	Optional	Discount code for coupon-based attribution
`compensation_type`	string	Optional	"flat_fee", "revenue_share", "cpc", "cpa", or "hybrid" (default: "flat_fee")
`commission_rate`	number	Optional	Revenue share percentage (for revenue_share/hybrid)
`cpc_rate`	number	Optional	Cost per click rate
`cpa_rate`	number	Optional	Cost per acquisition rate

Example

curl -X POST https://www.attriq.io/api/v1/creators \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Jones",
    "email": "sarah@example.com",
    "platform": "youtube",
    "flat_fee": 500,
    "coupon_code": "SARAH20"
  }'

Response (201)

{
  "data": {
    "id": "uuid",
    "name": "Sarah Jones",
    "email": "sarah@example.com",
    "platform": "youtube",
    "flat_fee": 500,
    "coupon_code": "SARAH20",
    "compensation_type": "flat_fee",
    "commission_rate": 0,
    "cpc_rate": 0,
    "cpa_rate": 0,
    "created_at": "2025-07-14T12:00:00Z"
  }
}

Workspace Stats

GET

/api/v1/stats

Get aggregate stats for your entire workspace

Query Parameters

Parameter	Type	Required	Description
`days`	integer	Optional	Lookback period in days, max 90 (default: 30)

Example

curl https://www.attriq.io/api/v1/stats?days=30 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": {
    "workspace": {
      "id": "uuid",
      "brand_name": "Your Brand",
      "plan": "growth"
    },
    "period_days": 30,
    "overview": {
      "total_creators": 8,
      "total_links": 24,
      "active_links": 20,
      "total_clicks": 12847,
      "unique_clicks": 10200,
      "bot_clicks": 342,
      "total_conversions": 156,
      "suspicious_conversions": 3,
      "total_revenue": 28450.00,
      "conversion_rate": 1.53
    },
    "top_creators": [
      {
        "id": "uuid",
        "name": "Sarah Jones",
        "platform": "youtube",
        "total_clicks": 3200,
        "unique_clicks": 2800,
        "total_conversions": 45,
        "total_revenue": 5670.00,
        "conversion_rate": 1.61,
        "roas": 11.34
      }
    ]
  }
}

Conversions (Webhooks)

Conversions are reported via webhooks from your website or payment platform. These endpoints use the same x-api-key header and are available on all plans (including Free).

POST

/api/webhooks/conversion

Report a conversion from your checkout or backend

Request Body (JSON)

Parameter	Type	Required	Description
`revenue`	number	Optional	Required nonnegative amount for purchases (e.g., 99.99). Omit or use 0 for non-purchase goals.
`goal_type`	string	Optional	purchase (default), signup, lead, or custom. Payment integrations continue to report purchases.
`goal_name`	string	Optional	Required for custom goals; must match the link goal name to count as a goal completion.
`order_id`	string	Optional	Your order/transaction ID
`currency`	string	Optional	ISO currency code (default: "USD")
`click_id`	string	Optional	UUID from localStorage.getItem('ls_click_id')
`coupon_code`	string	Optional	Discount code used at checkout
`source`	string	Optional	"webhook", "stripe", "shopify", "manual"
`metadata`	object	Optional	Any additional data to store

Example

curl -X POST https://www.attriq.io/api/webhooks/conversion \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revenue": 99.99,
    "order_id": "ORD-12345",
    "click_id": "click-uuid-from-localstorage",
    "coupon_code": "SARAH20"
  }'

Response (200)

{
  "success": true,
  "conversion_id": "uuid",
  "attributed_creator": true
}

Report a signup from your backend

curl -X POST https://www.attriq.io/api/webhooks/conversion \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_type": "signup",
    "click_id": "click-uuid-from-localstorage"
  }'

A link's goal describes what you want to measure; creating it does not automatically detect signups or leads. Send the event from your backend or configure a conversion rule. Purchases and revenue remain separate from non-purchase goal counts. Coupon-only or expired-click conversions are not guessed into a campaign.

For Shopify and Stripe webhook setup, see the Settings page in your dashboard.

Tracking checks, funnels & weekly insights

Verify your event setup

In Tracking setup checker, start a short-lived test for a link, open its test URL, and perform your configured goal. Redirect, smart-script, and conversion evidence are shown separately. Diagnostic events are isolated from production analytics and payouts. A browser test does not verify a payment provider's webhook delivery.

Connect funnel stages to actual events

Conversion funnels follow the same attributed click ID through ordered goals. Use signup and purchase, or custom events such as trial, download, and booked_call. Custom names must match exactly. Repeated events count once per click per stage; events without a valid attributed click do not become a guessed journey. These are not cross-device or unique-person funnels.

Explicit custom trial event, after the smart script loads

await window.attriq.track("custom", {
  goal_name: "trial",
  order_id: "unique-trial-event-id"
});

Compare complete weeks

Weekly insights compare two complete seven-day UTC windows, with sample sizes and currency-separated purchase revenue. Recommendations describe observed changes rather than proving causality. Weekly spend and ROAS are omitted because manually entered link budgets are all-time.

Existing backend conversion requests and payment webhooks continue to work. Your event implementation must send the click ID alongside each goal to connect the journey.

Products & Offers

Create a product, service, or download in Dashboard → Products & Offers, publish its hosted page, then create separate tracking links for flyers, social posts, and creators. Each QR code encodes its source-specific tracking link, not the shared page URL.

These endpoints require a signed-in workspace session, not an API key. Members with write access can create and edit offers; read-only members can view them. Existing plan limits apply to new tracking links.

GET

/api/v1/offers

List workspace offers, their stable public URLs, and write permission.

POST

/api/v1/offers

Create a draft or a complete published offer.

GET

/api/v1/offers/{offerId}

Read an offer, its associated source links, available creators, and write permission.

PATCH

/api/v1/offers/{offerId}

Save the complete editable fields. Set status to draft to unpublish without deleting tracking history.

POST

/api/v1/offers/{offerId}/links

Create a source-specific link to a published offer, with an optional creator, goal, campaign, and manual spend.

Published pages are available at /p/{slug}. The page URL stays the same when its content changes. Draft pages return 404. Price and availability are manual display fields, not inventory. Images use externally hosted HTTPS URLs; checkout, booking, and downloads stay with your existing provider.

Opening a page or clicking its action is not automatically counted as a conversion. A valid incoming click_id is forwarded to the external destination; that destination must retain it and report completed goals through your tracking integration. Compare source results in Campaigns. Hosted pages do not install your workspace tracking script, and diagnostic visits disable the external action.

Errors

All errors return a JSON object with an error field.

Status	Meaning
400	Bad Request — Missing or invalid parameters
401	Unauthorized — Missing or invalid API key
403	Forbidden — API access requires a paid plan
404	Not Found — Resource does not exist or doesn't belong to your workspace
409	Conflict — Resource already exists (e.g., duplicate slug)
429	Too Many Requests — Plan limit reached (creators, links, or rate limit)
500	Internal Server Error — Something went wrong on our end

Error response example

{
  "error": "Link limit reached (50 links on starter plan)",
  "upgrade_url": "https://www.attriq.io/dashboard/settings"
}

Rate Limits

API requests are rate-limited per workspace to ensure fair usage:

Plan	Rate Limit
Starter	60 requests/minute
Growth	120 requests/minute
Agency	300 requests/minute

When rate-limited, you'll receive a 429 response. Wait and retry with exponential backoff.

Quick Start

Create a creator, generate a tracking link, and check stats — all in 3 API calls:

# 1. Create a creator
curl -X POST https://www.attriq.io/api/v1/creators \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sarah Jones", "platform": "youtube", "flat_fee": 500}'

# 2. Create a tracking link (use the creator ID from step 1)
curl -X POST https://www.attriq.io/api/v1/links \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination_url": "https://yourbrand.com/sale", "creator_id": "CREATOR_ID"}'

# 3. Check stats after the link gets clicks
curl https://www.attriq.io/api/v1/stats \
  -H "x-api-key: YOUR_API_KEY"

Questions? Contact us at support@attriq.io