API Basics
An introduction to the Recomly API — authentication, base URLs, and how requests work.
The Recomly API is a REST API that lets you interact with your tenant programmatically. Any functionality available to your user account in the web application is available via the Recomly API.
Base URL
All API requests are made to:
https://api.recomly.comRequired headers
Every request must include the following headers:
| Header | Value |
|---|---|
Authorization | Bearer {keyId}:{secret} |
Content-Type | application/json |
You can generate and manage API keys from User Profile → API Keys in the Recomly dashboard.
Response format
All responses return JSON. Successful responses include the requested data at the top level. Error responses include an error field with a human-readable message:
{
"error": "API key is invalid or has been revoked."
}HTTP status codes
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad request — check your request body |
401 | Unauthorized — invalid or missing API key |
403 | Forbidden — your plan does not include API access |
404 | Resource not found |
429 | Rate limit exceeded |
500 | Internal server error |
Rate limits
API requests are rate-limited per tenant. If you exceed the limit you will receive a 429 response. Limits vary by plan — check your dashboard for your current limit.
Endpoints
Dashboard
| Method | Endpoint | Description |
|---|---|---|
GET | /api/app/dashboard | Get aggregated stats |
Campaigns
| Method | Endpoint | Description |
|---|---|---|
POST | /api/app/campaigns | Create a new referral campaign |
GET | /api/app/campaigns | List all campaigns |
GET | /api/app/campaigns/{campaignId} | Get a campaign |
PATCH | /api/app/campaigns/{campaignId} | Update a campaign |
DELETE | /api/app/campaigns/{campaignId} | Delete a campaign |
Advocates
| Method | Endpoint | Description |
|---|---|---|
POST | /api/app/campaigns/{campaignId}/invite | Invite an advocate |
GET | /api/app/campaigns/{campaignId}/advocates | List advocates |
GET | /api/app/campaigns/{campaignId}/advocates/{advocateId} | Get an advocate |
PATCH | /api/app/campaigns/{campaignId}/advocates/{advocateId} | Update an advocate |
DELETE | /api/app/campaigns/{campaignId}/advocates/{advocateId} | Delete an advocate |
POST | /api/app/campaigns/{campaignId}/advocates/{advocateId}/credit | Adjust credit balance |
GET | /api/app/campaigns/{campaignId}/advocates/{advocateId}/activity | List activity |
Referrals
| Method | Endpoint | Description |
|---|---|---|
GET | /api/app/campaigns/{campaignId}/referrals | List referrals |
POST | /api/app/campaigns/{campaignId}/referrals/{referralId}/convert | Convert a referral |