Plug Cordelia into the tools you already run

How tracking works

1. On the campaign, set a destination link (your website, app page or booking form) and add a KPI with the capture mode Your system tells us. Note the KPI key, for example first_order.
2. Each agent on the campaign gets a tracked Cordelia link. When a visitor opens it, Cordelia records the click and sends them to your destination with two parameters added: ref (the agent's link code) and cordelia_click (the id of that click).
3. Your site must store cordelia_click when the visitor lands (a cookie or your session is fine), and keep it with the user or order.
4. When the visitor signs up, books or pays, your server sends the stored cordelia_click back with a POST. Cordelia works out which agent to credit, checks the KPI's rules, and pays them or holds the payout.

https://yourshop.ng/signup?ref=AB12CD34&cordelia_click=90417

If you cannot store the click id, you can send the ref value instead. The click id is preferred because it also proves when the visitor arrived, which is how the KPI's attribution window is enforced.

Record a result

POST /api/v1/conversions.php with the header Authorization: Bearer <api_key>. Send JSON or form fields.

curl -X POST "https://cordelia.com.ng/api/v1/conversions.php" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": 128,
    "kpi": "first_order",
    "cordelia_click": 90417,
    "external_ref": "ORD-20931",
    "value": 18500,
    "customer_ref": "cust_7741"
  }'

A successful call returns 201. If the KPI has no hold period, the agent is paid straight away:

HTTP/1.1 201 Created

{
  "success": true,
  "duplicate": false,
  "conversion_id": 5521,
  "status": "paid",
  "payout_amount": 925.0,
  "release_at": null,
  "message": "Recorded and paid."
}

If the KPI holds payout for some days (for example "still active after 30 days"), the result is recorded as confirmed, release_at tells you when it will be paid, and Cordelia pays it automatically once that date passes:

HTTP/1.1 201 Created

{
  "success": true,
  "duplicate": false,
  "conversion_id": 5522,
  "status": "confirmed",
  "payout_amount": 500.0,
  "release_at": "2026-11-05 10:42:00",
  "message": "Recorded — payout is held until Nov 5."
}

Safe to retry

Every call needs an external_ref. Cordelia counts a given external_ref once per KPI on a campaign, so if your server times out and retries, or your queue delivers twice, the second call returns 200 with "duplicate": true and the original result. No second payout is made.

HTTP/1.1 200 OK

{
  "success": true,
  "duplicate": true,
  "conversion_id": 5521,
  "status": "paid",
  "payout_amount": 925.0,
  "release_at": null,
  "message": "Already recorded — nothing new was counted."
}

Per-agent limits and hold periods are set on the KPI. A result can later be reversed from the merchant dashboard, for example when an order is refunded; it stays on the record.

Errors

A failed call returns "success": false, a readable error and a machine-readable code. A missing or invalid API key returns 401 before any of these.

HTTP/1.1 404 Not Found

{
  "success": false,
  "error": "That click id does not belong to this campaign.",
  "code": "click_not_found"
}

List results

GET /api/v1/conversions.php returns the results on your campaigns, newest first.

curl "https://cordelia.com.ng/api/v1/conversions.php?campaign_id=128&status=paid&limit=25&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "total": 1,
  "limit": 25,
  "offset": 0,
  "data": [
    {
      "conversion_id": 5521,
      "campaign_id": 128,
      "kpi": "first_order",
      "event_shape": "transaction",
      "source": "api",
      "external_ref": "ORD-20931",
      "value": "18500.00",
      "payout_amount": "925.00",
      "status": "paid",
      "release_at": null,
      "created_at": "2026-10-06 10:42:11",
      "paid_at": "2026-10-06 10:42:11",
      "ref": "AB12CD34"
    }
  ]
}

Amounts in the list are returned as decimal strings.

Webhooks for results

Subscribe an endpoint to either of these events from your dashboard (they also appear in the event list above). Deliveries use the same signed format as every other Cordelia webhook: the body is { "event", "created_at", "data" }, and X-Cordelia-Signature is the HMAC-SHA256 of the raw body with your endpoint secret.

• conversion.recorded: a result was recorded on one of your campaigns, whether reported by an agent, entered by you, or sent by your system.
• conversion.paid: a result was confirmed and the agent has been paid.

POST https://yourshop.ng/hooks/cordelia
Content-Type: application/json
X-Cordelia-Event: conversion.paid
X-Cordelia-Signature: <HMAC-SHA256 of the raw body, using your endpoint secret>

{
  "event": "conversion.paid",
  "created_at": "2026-10-06T10:42:12+01:00",
  "data": {
    "id": 5521,
    "campaign_id": 128,
    "source": "api",
    "external_ref": "ORD-20931",
    "customer_ref": "cust_7741",
    "gross_value": 18500.0,
    "payout_amount": 925.0,
    "status": "paid",
    "release_at": null,
    "created_at": "2026-10-06 10:42:11",
    "paid_at": "2026-10-06 10:42:11",
    "kpi_key": "first_order",
    "kpi_label": "First order",
    "event_shape": "transaction",
    "link_code": "AB12CD34",
    "agent_ref": "agt_57"
  }
}

agent_ref is a stable reference to the agent (agt_ followed by their id); agent names and contact details are never included. link_code is the agent's tracked-link code, the same value as ref above.