Referrals.com
← Developer Portal

API Documentation v1

Authentication

POST/api/v1/auth/token

Exchange email and password for a JWT token.

Request Body

{ "email": "user@example.com", "password": "secret" }

Response

{ "success": true, "data": { "token": "eyJ...", "member": { "id": 1, "email": "...", "name": "..." } } }

Members

POST/api/v1/members

Register a new member (public).

Request Body

{ "email": "new@example.com", "name": "Jane Doe", "password": "securepass" }

Response

{ "success": true, "data": { "id": 42, "email": "...", "name": "...", "date_signedup": "..." } }
GET/api/v1/members/profileAuth Required

Get authenticated member profile.

Response

{ "success": true, "data": { "id": 1, "email": "...", "name": "...", "plan_id": 2, ... } }
POST/api/v1/members/api-keyAuth Required

Generate a new API key.

Response

{ "success": true, "data": { "api_key": "ref_abc123...", "date_generated": "..." } }
GET/api/v1/members/api-keyAuth Required

Get current API key.

Response

{ "success": true, "data": { "api_key": "ref_abc123...", "date_generated": "..." } }

Brands

GET/api/v1/brandsAuth Required

List all brands. Supports ?page=1&limit=20.

Response

{ "success": true, "data": { "brands": [...], "pagination": { ... } } }
POST/api/v1/brandsAuth Required

Create a new brand.

Request Body

{ "url": "https://mybrand.com", "description": "My Brand" }

Response

{ "success": true, "data": { "id": 5, "url": "...", "domain": "...", ... } }
GET/api/v1/brands/:brandIdAuth Required

Get a single brand by ID.

PUT/api/v1/brands/:brandIdAuth Required

Update a brand.

Request Body

{ "description": "Updated description", "logo_url": "https://..." }
DELETE/api/v1/brands/:brandIdAuth Required

Delete a brand.

GET/api/v1/brands/:brandId/statsAuth Required

Get brand analytics (campaigns, participants, shares, clicks, impressions).

Campaigns

GET/api/v1/campaignsAuth Required

List campaigns. Filter with ?brand_id=5. Supports pagination.

POST/api/v1/campaignsAuth Required

Create a new campaign.

Request Body

{ "name": "Summer Promo", "url_id": 5, "type_id": 1, "reward_type": 1 }
GET/api/v1/campaigns/:campaignIdAuth Required

Get campaign details including widget, reward, and contest info.

PUT/api/v1/campaigns/:campaignIdAuth Required

Update a campaign.

Request Body

{ "name": "Updated Name", "publish": "public" }
DELETE/api/v1/campaigns/:campaignIdAuth Required

Delete a campaign and related records.

GET/api/v1/campaigns/:campaignId/statsAuth Required

Get campaign stats (participants, shares, clicks, impressions, daily signups).

Participants

GET/api/v1/participantsAuth Required

List participants across your campaigns. Filter with ?campaign_id=10.

GET/api/v1/participants/:participantIdAuth Required

Get participant detail with shares, rewards, and invited emails.

POST/api/v1/signupsAuth Required

Register a participant signup externally.

Request Body

{ "campaign_id": 10, "email": "participant@example.com", "name": "John" }

Webhooks

GET/api/v1/webhooksAuth Required

List registered webhooks.

POST/api/v1/webhooksAuth Required

Register a new webhook URL.

Request Body

{ "link": "https://hooks.zapier.com/...", "campaign_id": 10 }
PUT/api/v1/webhooks/:webhookIdAuth Required

Update a webhook.

DELETE/api/v1/webhooks/:webhookIdAuth Required

Delete a webhook.

Zapier Integration

POST/api/v1/zapier/authAuth Required

Validate API key for Zapier authentication test.

GET/api/v1/zapier/contactsAuth Required

Get participants for Zapier polling trigger. Filter with ?campaign_id=10.

Billing

GET/api/v1/billing/plans

List all available subscription plans (public endpoint).