Referrals.com

Developer Support

Get help with your integration. Check our FAQ first, or reach out to the team.

Email Support

[email protected]

Community Forum

Ask the community and our team

Knowledgebase

Guides and best practices

API Status
API v1 — Operational
Widget API — Operational
Webhooks — Operational
Troubleshooting Checklist
  • Verify your API key is in the X-API-Key header, not query params
  • Check Content-Type is application/json for POST/PUT requests
  • Ensure IDs in URLs are integers, not strings
  • For 404 errors, verify the resource belongs to your account
  • For webhook failures, check the URL is publicly reachable and returns a 2xx response

Frequently Asked Questions

How do I get an API key?
Sign up for a Referrals.com account, go to the API Keys page in your dashboard, and click "Generate API Key". You can also call POST /api/v1/members/api-key programmatically.
What is the rate limit?
There is currently no hard rate limit, but we ask that you keep requests under 100/minute per API key. Excessive usage may be throttled.
I'm getting a 401 "Invalid or missing API key" error.
Make sure you're sending the key in the X-API-Key header (not as a query parameter). The key should start with "ref_". Check that it hasn't been regenerated — generating a new key doesn't invalidate old ones, but double-check which key you're using.
Can I have multiple API keys?
Yes. Each call to POST /api/v1/members/api-key creates a new key. All keys for your account remain active.
Do I need a paid plan to use the API?
Most API endpoints work on the free plan. Publishing campaigns as "public" requires an active paid subscription.
How do webhooks work?
Register a URL via POST /api/v1/webhooks. When a participant signs up for the associated campaign, we POST a JSON payload to your URL with the event details.
Why isn't my referral reward being processed?
Check that: (1) the campaign has goal_type set to 'signup', (2) a campaign_reward record exists, (3) for coupon rewards, unused coupons are available, (4) the referring participant hasn't already received a reward for this campaign.
Can I use the API from the browser (CORS)?
Yes. All /api/v1/* endpoints return CORS headers allowing requests from any origin. OPTIONS preflight requests are handled automatically.