Skip to main content
Welcome to the FirstPromoter V1 API. This is our original REST API for managing promoters, leads, payouts, rewards, and tracking events programmatically.
All API calls are sent as key-value pair parameters (query string or form-encoded body — see the parameters listed on the right for each endpoint), not as a JSON request body. Responses are always returned in JSON format.
Building something new? Consider our V2 API instead — it’s more robust and actively developed. This V1 API remains fully supported for existing integrations.

​
Base URL

Requests are made directly against https://firstpromoter.com, followed by the resource path, for example:

​
Authentication

All requests must include your account’s API key in the X-API-KEY header. See the Authentication page for details on finding your key.

​
Rate Limits

To ensure fair usage and system stability, requests authenticated with an API key are limited to:
  • 450 requests per minute per API key
Exceeding this limit will result in a 429 Too Many Requests response.

​
Pagination

List endpoints (e.g. GET /promoters, GET /leads, GET /payouts, GET /rewards) are paginated using page and per_page query parameters. Pagination metadata (Total, Per-Page, Link) is returned in the response headers rather than in the JSON body.

​
Errors

Error responses are JSON, but the shape can vary by endpoint:
  • Most handled errors (e.g. a referenced campaign or promoter not found) return {"error": "<message>"}.
  • Validation failures on create/update endpoints typically return the record’s errors directly, e.g. {"email": ["has already been taken"]}.
  • An invalid or missing API key returns a 401 with the plain text body "Bad credentials".
Always check the HTTP status code first, and refer to each endpoint’s own documentation for its specific error responses.