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

All API requests are authenticated using your workspace API key, passed in the x-api-key header.

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://trk.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	Required	ID of the creator this link belongs to
`utm_campaign`	string	Optional	Campaign name for UTM tagging
`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://trk.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"
  }
}

Link Stats

GET

/api/v1/links/:linkId/stats

Get click & conversion stats for a specific link

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/links/LINK_ID/stats?days=7 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": {
    "link": {
      "id": "uuid",
      "slug": "sarah-summer",
      "tracking_url": "https://trk.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	Required	Purchase amount (e.g., 99.99)
`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
}

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

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