№ 01 · Reference

Referrio API

REST over HTTPS. JSON in, JSON out. Predictable resource URLs and real HTTP status codes. Authenticate with a single header and point your backend at https://referrio.co.uk.

№ 02

Authentication

Every authenticated request must send an X-API-Key header. Create and rotate keys from the dashboard under Business → API Keys. Treat keys like passwords — never expose them in browser code.

curl 'https://referrio.co.uk/api/public/v1/users' \
  -H 'X-API-Key: rk_live_YOUR_KEY'

Platform-scoped keys (rk_plat_…) must additionally pass business_id in the request body or as a ?business_id= query parameter for writes.

№ 03

Errors

The API uses standard HTTP status codes. Error bodies always include an error string and, for validation failures, a details object from Zod.

200 / 201	Success.
400	Invalid JSON or validation failure.
401	Missing or invalid API key.
402	Plan referrer limit reached — upgrade required.
403	Referrer is not active, or operation not permitted.
404	Resource not found.
409	Conflict — e.g. referrer with that email already exists in this business.
500	Internal server error.

№ 04

Rate limits

Endpoints are rate limited per API key. Every call is logged with timing and status to the API usage log, visible from your dashboard. If you need higher limits, get in touch.

Users (Referrers)

Endpoint

Create a user

POST/api/public/v1/users

Create a new referrer. Both email and mobile_number are required — they're how Referrio delivers rewards and lets the referrer log in to their portal. If a referrer with the same email or mobile_number already exists in another business, the same referral_code is reused so a person keeps one code everywhere. New referrers default to status "pending" — only "active" referrers can use their code.

Body parameters

`email`required string	Email address. Validated with Loqate when enabled.
`mobile_number`required string	Mobile number in E.164 or local format. Validated with Loqate when enabled.
`first_name` string	Referrer's first name.
`last_name` string	Referrer's last name.
`external_id` string	Your internal ID for this user.
`referral_code` string	Override the auto-generated code. 3–40 chars, alphanumeric / -/_.
`status` string	pending \| active \| suspended \| cancelled. Defaults to pending.
`date_of_birth` string	Optional ISO date (YYYY-MM-DD). Used for campaigns like automatic birthday rewards.
`metadata` object	Free-form JSON you can attach (plan, tier, source, etc.).

Request

curl -X POST 'https://referrio.co.uk/api/public/v1/users' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "external_id": "cust_123",
  "email": "jane@example.com",
  "mobile_number": "+44 7700 900123",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-05-12",
  "metadata": {
    "plan": "pro"
  }
}'

Example response

{
  "data": {
    "id": "8b1f...",
    "referral_code": "jane-A1B2C3",
    "email": "jane@example.com",
    "mobile_number": "+447700900123",
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "pending",
    "created_at": "2026-06-12T10:00:00Z"
  }
}

Endpoint

List users

GET/api/public/v1/users?email=jane@example.com

List/lookup your referral users, newest first. Use query filters to search by email, mobile number, external ID or referral code. An empty data array (and exists:false) means no match. Each row includes id, external_id, email, mobile_number, first_name, last_name, referral_code, status, date_of_birth, metadata, created_at and updated_at.

Query parameters

`email` string	Filter by email address (exact match, normalised to lowercase).
`mobile_number` string	Filter by mobile number (exact match, normalised automatically). Accepts E.164 or local format.
`external_id` string	Filter by your internal user ID (exact match).
`referral_code` string	Filter by referral code (exact match, case-insensitive).
`limit` integer	Max results to return. Default 50, max 200.

Request

curl -X GET 'https://referrio.co.uk/api/public/v1/users?email=jane@example.com' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Example response

{
  "exists": true,
  "count": 1,
  "data": [
    {
      "id": "8b1f...",
      "external_id": "cust_123",
      "email": "jane@example.com",
      "mobile_number": "+447700900123",
      "first_name": "Jane",
      "last_name": "Doe",
      "referral_code": "jane-A1B2C3",
      "status": "active",
      "date_of_birth": "1990-05-12",
      "metadata": {
        "plan": "pro"
      },
      "created_at": "2026-06-12T10:00:00Z",
      "updated_at": "2026-06-12T14:30:00Z"
    }
  ]
}

Endpoint

Get a user

GET/api/public/v1/users/:id

Retrieve a user by their id, external_id, or referral_code. Response includes the referrer (id, external_id, email, mobile_number, first_name, last_name, referral_code, status, date_of_birth, metadata, timestamps) plus their events and rewards.

Request

curl -X GET 'https://referrio.co.uk/api/public/v1/users/:id' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Example response

{
  "data": {
    "id": "8b1f...",
    "external_id": "cust_123",
    "email": "jane@example.com",
    "mobile_number": "+447700900123",
    "first_name": "Jane",
    "last_name": "Doe",
    "referral_code": "jane-A1B2C3",
    "status": "active",
    "date_of_birth": "1990-05-12",
    "metadata": {
      "plan": "pro"
    },
    "created_at": "2026-06-12T10:00:00Z",
    "updated_at": "2026-06-12T14:30:00Z",
    "events": [],
    "rewards": []
  }
}

Endpoint

Update a user

PATCH/api/public/v1/users/:id

Update an existing referrer. Useful for changing status from "pending" to "active" so they can start referring. You can also update email, mobile_number, first_name, last_name, external_id, or metadata. The id must be the referrer's UUID (external_id and referral_code are not accepted for updates).

Body parameters

`status` string	pending \| active \| suspended \| cancelled
`email` string	Email address. Normalised to lowercase.
`mobile_number` string	Mobile number in E.164 or local format. Normalised automatically.
`first_name` string	Referrer's first name.
`last_name` string	Referrer's last name.
`external_id` string	Your internal ID for this user.
`date_of_birth` string	ISO date (YYYY-MM-DD). Pass null to clear.
`metadata` object	Free-form JSON object. Replaces the existing metadata entirely.

Request

curl -X PATCH 'https://referrio.co.uk/api/public/v1/users/:id' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "active"
}'

Example response

{
  "data": {
    "id": "8b1f...",
    "referral_code": "jane-A1B2C3",
    "email": "jane@example.com",
    "mobile_number": "+447700900123",
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "active",
    "created_at": "2026-06-12T10:00:00Z",
    "updated_at": "2026-06-12T14:30:00Z"
  }
}

Endpoint

Delete a user

DELETE/api/public/v1/users/:id

Remove a referrer. Their referral_code stops working immediately.

Request

curl -X DELETE 'https://referrio.co.uk/api/public/v1/users/:id' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Referrals

Endpoint

Track a referral event

POST/api/public/v1/referrals

Record a visit, signup, or sale against a referral code. Triggers reward evaluation against any matching active campaigns. Returns 403 if the referrer status is not "active".

Body parameters

`referral_code`required string	The referrer's code.
`event_type`required string	One of: visit, signup, sale.
`sale_amount` number	Required for sale events used by sale_amount campaigns.
`referee_email` string	Email of the person who was referred.
`referee_external_id` string	Your ID for the referee.
`metadata` object	Free-form JSON metadata.

Request

curl -X POST 'https://referrio.co.uk/api/public/v1/referrals' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "referral_code": "jane-A1B2C3",
  "event_type": "sale",
  "sale_amount": 99,
  "referee_email": "friend@example.com"
}'

Endpoint

List referral events

GET/api/public/v1/referrals

List recent referral events with referrer details. Returns up to 200 events, newest first.

Request

curl -X GET 'https://referrio.co.uk/api/public/v1/referrals' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Endpoint

Validate a referral code (public)

GET/api/public/v1/track/:code

Public endpoint — no API key required. Useful for storefront widgets validating a code at checkout. Returns 403 when the referrer is not active.

Request

curl -X GET 'https://referrio.co.uk/api/public/v1/track/:code' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Campaigns

Endpoint

List campaigns

GET/api/public/v1/campaigns

List all reward campaigns for your business.

Request

curl -X GET 'https://referrio.co.uk/api/public/v1/campaigns' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Endpoint

Create a campaign

POST/api/public/v1/campaigns

Define the reward, trigger and eligibility rules.

Body parameters

`name`required string	Campaign name.
`reward_type` string	cash \| voucher \| custom (default cash).
`reward_amount` number	Reward value in the chosen currency.
`reward_currency` string	ISO-4217 code, e.g. GBP, USD, EUR.
`trigger_type` string	signup \| sale_amount \| sale_count \| custom.
`min_sale_amount` number	Threshold for sale_amount triggers.
`min_sale_count` number	Threshold for sale_count triggers.
`active` boolean	Defaults to true.

Request

curl -X POST 'https://referrio.co.uk/api/public/v1/campaigns' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Refer & earn £20",
  "reward_type": "cash",
  "reward_amount": 20,
  "reward_currency": "GBP",
  "trigger_type": "sale_amount",
  "min_sale_amount": 50
}'

Vouchers

Endpoint

Upload vouchers

POST/api/public/v1/vouchers

Upload a batch of voucher codes to the pool. Up to 1,000 vouchers per request.

Request

curl -X POST 'https://referrio.co.uk/api/public/v1/vouchers' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "campaign_id": "<campaign-uuid>",
  "currency": "GBP",
  "vouchers": [
    {
      "code": "SAVE10-ABC",
      "value": 10
    },
    {
      "code": "SAVE10-DEF",
      "value": 10
    }
  ]
}'

Endpoint

List vouchers

GET/api/public/v1/vouchers

List vouchers in your pool (up to 500).

Request

curl -X GET 'https://referrio.co.uk/api/public/v1/vouchers' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Rewards

Endpoint

List rewards

GET/api/public/v1/rewards?status=issued

Request

curl -X GET 'https://referrio.co.uk/api/public/v1/rewards?status=issued' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json'

Endpoint

Update a reward

PATCH/api/public/v1/rewards?id=<reward-uuid>

Update a reward's status and/or reason. Setting status to "paid" stamps paid_at automatically. `reason` is an optional free-text note (max 500 chars) explaining why the reward was issued.

Request

curl -X PATCH 'https://referrio.co.uk/api/public/v1/rewards?id=<reward-uuid>' \
  -H 'X-API-Key: rk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "paid",
  "reason": "Referred a new customer"
}'

Webhooks

Events & payloads

Configure a webhook URL in your dashboard to receive signed POST requests when these events occur.

Event	Description
referrer.created	New referrer added (any status).
referrer.status_changed	Referrer status moved between pending / active / suspended / cancelled.
referrer.deleted	Referrer removed.
referral.visit	Referral link or code visited.
referral.signup	Referee signed up via a referral code.
referral.sale	Referee completed a sale via a referral code.
reward.issued	Reward generated from a qualifying event.
reward.paid	Cash reward marked as paid.
reward.cancelled	Reward cancelled / refunded.

Example payload

{
  "id": "evt_01HZ...",
  "type": "referrer.status_changed",
  "created_at": "2026-06-12T22:10:00Z",
  "data": {
    "referrer": {
      "id": "<uuid>",
      "external_id": "cust_123",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "mobile_number": "+44 7700 900123",
      "referral_code": "jane-A1B2C3",
      "status": "active",
      "previous_status": "pending"
    }
  }
}

Signature verification

Each delivery includes an X-Referrio-Signature header — an HMAC-SHA256 of the raw request body using your webhook secret. Always verify the signature before processing the payload.

# Signature header is sent by Referrio:
# X-Referrio-Signature: sha256=<hex>
# Recompute on your side using the raw request body:
echo -n "$RAW_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"