Blue's Affiliate API

This API enables partner systems to integrate with BlueDesk's affiliate management platform. It provides endpoints for affiliate authentication, click tracking, revenue reporting, and payout management.

The API is designed for server-to-server communication. Your backend calls these endpoints on behalf of affiliates — the affiliate portal should never call BlueDesk directly.

Authentication

All requests must include an API key in the X-API-Key header. API keys are issued by BlueDesk administrators.

Header

X-API-Key: bdp_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without a valid API key will receive a 401 Unauthorized response.

Base URL

https://affiliate-api.bluedesk.is

Staging environment: https://affiliate-api-staging.bluedesk.is

Rate Limits

Scope	Limit	Window
Global (all endpoints)	1,000 requests	Per minute
Login	10 requests	Per minute per IP
Click ingestion	500 requests	Per minute per API key

Exceeded limits return 429 Too Many Requests.

Error Handling

The API uses standard HTTP status codes:

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request (validation error)
`401`	Unauthorized (missing/invalid API key or credentials)
`404`	Resource not found
`409`	Conflict (e.g., duplicate email)
`429`	Rate limit exceeded
`500`	Server error

Error responses return a JSON object with an error field:

{
  "error": "Amount exceeds available balance"
}

POST /api/v1/partner/auth/login

Validate affiliate credentials. Returns affiliate identity for your system to issue its own session token.

Request Body

{
  "email": "affiliate@example.com",
  "password": "their-password"
}

Response

200 Success

{
  "affiliate": {
    "id": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
    "name": "Demo Affiliate",
    "email": "affiliate@example.com",
    "referralLink": "https://bluecarrental.is?ref=demo-affiliate"
  }
}

401 Invalid credentials

Only affiliates with status approved or active can log in. Unapproved, rejected, or deactivated affiliates receive 401.

Submit Affiliate Application

POST /api/v1/partner/applications

Submit a new affiliate application from the "Join Us" form. Creates an affiliate with status unapproved.

Request Body

{
  "email": "new-affiliate@example.com",
  "password": "securepassword123",
  "firstName": "John",
  "lastName": "Smith",
  "companyName": "Nordic Travel Co",
  "website": "https://nordictravel.co",
  "instagram": "@nordictravel",
  "tiktok": "",
  "youtube": "",
  "facebook": "nordictravel"
}

Parameters

Field	Required	Description
`email`	Yes	Affiliate's email address (unique)
`password`	Yes	Password (min 8 characters)
`firstName`	Yes	First name
`lastName`	Yes	Last name
`companyName`	No	Company or property name
`website`	No	Website URL
`instagram`	No	Instagram handle
`tiktok`	No	TikTok handle
`youtube`	No	YouTube channel
`facebook`	No	Facebook page

Response

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug": "nordic-travel-co",
  "email": "new-affiliate@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "companyName": "Nordic Travel Co",
  "status": "unapproved",
  "createdAt": "2026-03-31T12:00:00Z",
  "updatedAt": "2026-03-31T12:00:00Z"
}

409 Email already registered

Record Click Event

POST /api/v1/partner/affiliates/{affiliateId}/clicks

Record a referral link click. Call this whenever a visitor arrives via an affiliate's referral link.

Path Parameters

Parameter	Description
`affiliateId`	The affiliate's UUID (from login response)

Request Body

{
  "country": "IS",
  "sourceApp": "website"
}

Both fields are optional. country is the visitor's country code, sourceApp identifies the referring platform.

Response

201 Created

{
  "status": "ok"
}

Daily Click Breakdown

GET /api/v1/partner/affiliates/{affiliateId}/clicks

Get daily click counts for a given month. Every day in the month is included, even if the count is zero.

Query Parameters

Parameter	Required	Description
`month`	Yes	Month number (1–12)
`year`	Yes	Four-digit year

Response

200 Success

{
  "clicksPerDay": [
    { "date": "2026-03-01T00:00:00Z", "value": 94 },
    { "date": "2026-03-02T00:00:00Z", "value": 87 },
    { "date": "2026-03-03T00:00:00Z", "value": 0 },
    ...
  ]
}

Total Clicks for Month

GET /api/v1/partner/affiliates/{affiliateId}/clicks/total

Get the total click count for a given month.

Query Parameters

Parameter	Required	Description
`month`	Yes	Month number (1–12)
`year`	Yes	Four-digit year

Response

200 Success

{
  "total": 1234
}

Monthly Revenue

GET /api/v1/partner/affiliates/{affiliateId}/revenue/total

Get total revenue generated through the affiliate's referral link for a given month.

Query Parameters

Parameter	Required	Description
`month`	Yes	Month number (1–12)
`year`	Yes	Four-digit year

Response

200 Success

{
  "total": 45000.00
}

Returns 0 if no revenue data has been recorded for the period.

Expected Commission

GET /api/v1/partner/affiliates/{affiliateId}/commission/expected

Get expected commission for a given month.

Query Parameters

Parameter	Required	Description
`month`	Yes	Month number (1–12)
`year`	Yes	Four-digit year

Response

200 Success

{
  "total": 2250.00
}

Returns 0 if no commission data has been recorded for the period.

Payout Balance

GET /api/v1/partner/affiliates/{affiliateId}/payouts/balance

Get the affiliate's current available payout balance.

Response

200 Success

{
  "availableBalance": 2845.00
}

Payout History

GET /api/v1/partner/affiliates/{affiliateId}/payouts/history

Get the full payout transaction history for an affiliate.

Response

200 Success

{
  "history": [
    {
      "id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
      "affiliateId": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
      "amount": 1200.00,
      "status": "paid",
      "requestDate": "2026-01-05",
      "paidDate": "2026-01-10",
      "createdAt": "2026-01-05T10:00:00Z",
      "updatedAt": "2026-01-10T14:00:00Z"
    },
    {
      "id": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
      "affiliateId": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
      "amount": 500.00,
      "status": "pending",
      "requestDate": "2026-03-15",
      "paidDate": null,
      "createdAt": "2026-03-15T09:30:00Z",
      "updatedAt": "2026-03-15T09:30:00Z"
    }
  ]
}

Payout Status Values

Status	Description
`pending`	Request submitted, awaiting approval
`approved`	Approved by administrator, awaiting payment
`paid`	Payment completed
`rejected`	Request rejected by administrator

Submit Payout Request

POST /api/v1/partner/affiliates/{affiliateId}/payouts/request

Submit a payout request. The amount is validated against the affiliate's available balance.

Request Body

{
  "amount": 500.00
}

Response

201 Created

{
  "id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
  "affiliateId": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
  "amount": 500.00,
  "status": "pending",
  "requestDate": "2026-03-31",
  "paidDate": null,
  "createdAt": "2026-03-31T12:00:00Z",
  "updatedAt": "2026-03-31T12:00:00Z"
}

400 Validation error

{
  "error": "Amount exceeds available balance"
}

The balance is deducted atomically when the request is created. If the request is later rejected, the balance is restored by an administrator.

General Notes

Topic	Detail
Date format	ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ` for timestamps, `YYYY-MM-DD` for dates)
Currency	All monetary amounts are in ISK (Icelandic Króna)
Affiliate ID	UUID returned from the login endpoint. Include in all subsequent requests.
Content-Type	All requests and responses use `application/json`
Empty arrays	List endpoints return `[]` (not `null`) when no records exist

Questions? Contact gudmundur@bluecarrental.is