--- id: "api-reference/overview" type: "doc" url: "https://affitor.com/docs/api-reference/overview" --- # API Reference > Base URL, authentication, request/response envelope, and available endpoints for the Affitor Tracking API. The Affitor Tracking API lets your backend record affiliate events — clicks, signups, sales, and refunds — and retrieve program performance data. --- ## Base URL ```text https://api.affitor.com ``` All paths below are relative to this base. Strapi serves v1 routes under `/api`, so the full path for a tracking endpoint is: ```text https://api.affitor.com/api/v1/track/sale ``` :::note A machine-readable [OpenAPI 3.1 spec](https://affitor.com/docs/openapi.yaml) is available for the tracking endpoints — import it into Postman, Insomnia, code generators, or an AI coding agent. ::: --- ## Authentication Different endpoints use different auth modes. | Endpoint | Auth required | How to pass | |----------|--------------|-------------| | `POST /api/v1/track/click` | None | No token needed | | `POST /api/v1/track/lead` | Optional (server mode) | `Authorization: Bearer ` | | `POST /api/v1/track/sale` | Required | `Authorization: Bearer ` | | `POST /api/v1/track/refund` | Required | `Authorization: Bearer ` | Your **program API key** (`api_token`) is found in the Affitor dashboard under your program settings. ### Server mode vs browser mode (lead endpoint) `POST /api/v1/track/lead` supports two modes: - **Browser mode** — called by `affitor-tracker.js` from the customer's browser. No Bearer token. Attribution is proved by the `click_id` cookie value passed in the body. - **Server mode** — called from your backend. Include `Authorization: Bearer `. Pass `customer_key` or `click_id` to identify the customer. --- ## Response envelope All endpoints return JSON. A successful tracking call includes `"success": true`; the readiness endpoint returns its verdict object instead, with no `success` field. On an error, `error` is an object — never a plain string. **Success shape:** ```json { "success": true } ``` Sale and refund responses include additional IDs: ```json { "success": true, "sale_id": 42, "commission_id": 17, "message": "Sale tracked successfully" } ``` **Error shape:** ```json { "data": null, "error": { "status": 400, "name": "BadRequestError", "message": "transaction_id is required and must be a string", "details": {} } } ``` Read `error.message`, not `error` — interpolating the object prints `[object Object]`. The readiness endpoint uses a different envelope, and so does any endpoint refusing a key past its rotation deadline. Both shapes are laid out in the [error reference](/docs/api-reference/errors#error-response-shape). --- ## Endpoint families ### `/api/v1/track/*` — Tracking API (v1) The primary integration surface. Writes to the v1 event tables (`affiliate_click_events`, `affiliate_lead_events`, `affiliate_sale_events`). | Method | Path | Purpose | |--------|------|---------| | `POST` | `/api/v1/track/click` | Record an affiliate link click | | `POST` | `/api/v1/track/lead` | Record a customer signup | | `POST` | `/api/v1/track/sale` | Record a completed sale and create a commission | | `POST` | `/api/v1/track/refund` | Reverse the commission for a previously tracked sale | ### `/api/tracking/*` — Dashboard endpoints There is **no** `/api/tracking/` alias for click, lead, sale, or refund. The four `/api/v1/track/*` paths above are the only ones that accept tracking calls from your backend. The `/api/tracking/` paths that do exist back the Affitor dashboard, not a server-to-server integration. They authenticate with a signed-in dashboard session and require an active workspace membership on the program — taken from the path, or from `program_id` in the body on the two `POST` routes that have no path parameter. A Bearer program API key is not accepted on any of them: | Method | Path | Purpose | |--------|------|---------| | `GET` | `/api/tracking/status/:programId` | [Integration status](/docs/api-reference/status) for the program | | `GET` | `/api/tracking/events/:programId` | [Recent click, lead, and sale events](/docs/api-reference/events) | | `GET` | `/api/tracking/performance/:programId` | [Aggregated performance metrics](/docs/api-reference/performance) | | `GET` | `/api/tracking/readiness/:programId` | Readiness verdict for the program | | `POST` | `/api/tracking/test` | Create a test event from the dashboard verifier | | `POST` | `/api/tracking/check-test-events` | Check whether those test events landed | | `POST` | `/api/tracking/run-verification/:programId` | Run the synthetic click → lead → sale chain | To reach readiness from your own backend, call `GET /api/v1/programs/me/readiness` with your program API key instead — it derives the program from the key, so there is no program ID in the path. --- ## Test mode Pass `"additional_data": { "test_mode": true }` in any tracking request body to create a flagged test record without affecting real attribution, commission, or metric state. Test records are marked `is_test: true` in the database. --- ## Endpoint pages Record an affiliate link click and create the customer attribution relationship. Record a customer signup and link it to a prior click. Record a completed sale, create a commission, and update program metrics. Reverse the commission for a sale that was refunded. Check program integration status and health. Retrieve click, lead, and sale event records for a program. Retrieve aggregated performance metrics for a program.