Recomly APIEndpoints
Create campaign
Create a new referral campaign for your organization.
POST /api/app/campaigns
Creates a new referral campaign. Campaigns define the reward structure and settings that govern how advocates earn and refer friends. The campaign is immediately usable once created.
Request
See API Basics for required headers.
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Campaign name. Max 100 characters. |
rewardMode | "fixed" | "percent" | Yes | How reward values are interpreted. fixed = cents (e.g. 2500 = $25.00). percent = basis points (e.g. 500 = 5%). |
advocateRewardValue | integer | Yes | Reward amount for the advocate when a referral converts. Unit depends on rewardMode. |
friendRewardValue | integer | Yes | Reward amount for the referred friend when they convert. Unit depends on rewardMode. |
status | "active" | "paused" | No | Initial campaign status. Defaults to "active". |
expiresAt | string (ISO 8601) | No | Date and time the campaign stops accepting new referrals. Omit for no expiry. |
maxReferralsPerAdvocate | integer (1–200) | No | Maximum number of referrals an individual advocate can send. Defaults to 10. |
For percent campaigns, reward amounts are in basis points — 100 basis points equals 1%. The maximum value is 10000 (100%). The actual payout amounts are calculated from the job value you record at conversion time.
Sample request
curl -X POST https://api.recomly.com/api/app/campaigns \
-H "Authorization: Bearer rk_live_abc123:def456" \
-H "Content-Type: application/json" \
-d '{
"name": "Spring Referral Drive",
"rewardMode": "fixed",
"advocateRewardValue": 2500,
"friendRewardValue": 1500,
"status": "active",
"maxReferralsPerAdvocate": 20
}'Sample response
Status: 201 Created
{
"campaign": {
"campaignId": "c7a3f1d2-84b0-4e9a-bcd2-1f3e5a7c9012",
"orgId": "a1b2c3d4-0000-4000-8000-e5f6a7b8c9d0",
"name": "Spring Referral Drive",
"status": "active",
"rewardMode": "fixed",
"advocateRewardValue": 2500,
"friendRewardValue": 1500,
"maxReferralsPerAdvocate": 20,
"createdAt": "2026-04-04T14:00:00.000Z",
"updatedAt": "2026-04-04T14:00:00.000Z"
}
}Error responses
See API Basics for standard status codes and error response format.