Members are users of your app (or, soon, non-user affiliates) who are part of your referral programme. Members refer users and earn rewards for new customers they bring to your app.
List members
GET https://api.refermo.co/v1/members/
Request parameters
None.
Response values
Pagination
count
(int)
Total results for this query (including other pages of results).next
(string)
The URL for the next page of results, ornull
if there isn't one.previous
(string)
The URL for the previous page of results, ornull
if there isn't one.
Member data
id
(string, 32 chars)
The unique Refermo ID for this member.identifier
(string, max 100 chars)
This is an unchanging, unique ID from your app.email
(string)first_name
(string ornull
)last_name
(string ornull
)code
(string, max 30 chars)stats
(dictionary)campaign
(dictionary ornull
)
A campaign object.subscription
(dictionary ornull
)
A subscription object. Subscriptions are attached the members so members can earn credit on their subscriptions.
Example response
HTTP 200 OK
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": "e65d11dfffdedde824a711ca5a7ba4ee",
"identifier": "dan@gloathost.com",
"email": "dan@gloathost.com",
"first_name": "Dan",
"last_name": null,
"code": "YE48UNRJ",
"stats": {
"link_clicks": 0,
"referrals": 0,
"conversions": 0,
"credit_earned": "0.00",
"commission_earned": "0.00",
"currency": "USD"
},
"campaign": {
"id": "4d0e29b3",
"name": "Referrals",
"allows_credit": true,
"credit_amount": "0.00",
"credit_currency": "USD"
},
"subscription": null
},
{
"id": "a803529b4058c8dfb4f557b0429543be",
"identifier": "danr@gmail.com",
"email": "danr@gmail.com",
"first_name": null,
"last_name": null,
"code": "1PNWDBPR",
"stats": {
"link_clicks": 20,
"referrals": 3,
"conversions": 1,
"credit_earned": "15.00",
"commission_earned": "0.00",
"currency": "USD"
},
"campaign": {
"id": "4d0e29b3",
"name": "Referrals",
"allows_credit": true,
"credit_amount": "0.00",
"credit_currency": "USD"
},
"subscription": {
"id": 673929,
"unit_price": null,
"currency": "USD",
"status": "active",
"email": "danr@gmail.com",
"next_bill_date": "2022-08-31",
"last_bill_date": "2021-08-31",
"plan": {
"id": 736382,
"name": "Annual",
"amount": "59.00",
"currency": "USD",
"descriptor": "US$59.00/year"
}
}
},
...
]
}
Filters
List members from a specific campaign
To list members for one of your campaigns, use the query parameter campaign
and provide the id
of the campaign, like this:
GET https://api.refermo.co/v1/members/?campaign=1072cf3e
Retrieve a member
GET https://api.refermo.co/v1/members/[id]/
Request parameters
id
The member's Refermo ID.
Response values
id
(string, 32 chars)
The unique Refermo ID for this member.identifier
(string, max 100 chars)
This is an unchanging, unique ID from your app.email
(string)first_name
(string ornull
)last_name
(string ornull
)code
(string, max 30 chars)stats
(dictionary)campaign
(dictionary ornull
)
A campaign object.subscription
(dictionary ornull
)
A subscription object.
Example response
HTTP 200 OK
{
"id": "e65d11dfffdedde824a711ca5a7ba4ee",
"identifier": "dan@gmail.com",
"email": "dan@gmail.com",
"first_name": null,
"last_name": null,
"code": "YE48UNRJ",
"stats": {
"link_clicks": 20,
"referrals": 3,
"conversions": 1,
"credit_earned": "15.00",
"commission_earned": "0.00",
"currency": "USD"
},
"campaign": {
"id": "4d0e29b3",
"name": "From API",
"allows_credit": true,
"credit_amount": "10.00",
"credit_currency": "USD"
},
"subscription": {
"id": 673929,
"unit_price": null,
"currency": "USD",
"status": "active",
"email": "danr@gmail.com",
"next_bill_date": "2022-08-31",
"last_bill_date": "2021-08-31",
"plan": {
"id": 736382,
"name": "Annual",
"amount": "59.00",
"currency": "USD",
"descriptor": "US$59.00/year"
}
}
}
Errors
If a member cannot be found, the endpoint will return a HTTP 404
response with an error message.
HTTP 404 Not Found
{
"detail": "Not found."
}
Create a member
POST https://api.refermo.co/v1/members/
Request parameters
- None
Request values
identifier
(string, max 100 chars) required
A unique identifier for this user in your app. Could be a user ID, username or email address. This value should be something that never changes in your app.email
(string) required
The email address of this member. Refermo uses this to contact your members about rewards or their account.first_name
(string, max 50 chars)
Not required but useful for personalisation of Refermo's automated emails (eg when a conversion is made).last_name
(string, max 50 chars)code
(string, max 30 chars) default is a randomly-generated 8-character string
A unique code used in a member's referral link, likeyourdomain.com/?via=CODE
.
If you don't specifiy a code, Refermo will generate an 8-character random string of numbers and capital letters, likeB6D389J5
.campaign
(dictionary)
To add a member to an existing campaign, use a dictionary like{"id": "[campaign_id]"}
. If a campaign with that ID doesn't exist, the request will fail with anHTTP 400
error (see below). Keys other thanid
are allowed but will not be saved.
Note: members cannot earn rewards if they're not in a campaign!subscription
(dictionary)
The member will be attached to the subscription with theid
value. Theid
is the ID from Paddle (which is copied over into Refermo), so if you already have the Paddle ID of each subscription in your app, you can easily attach subscriptions to members.
If a subscription with that ID doesn't exist, the request will fail with anHTTP 400
error (see below). Keys other thanid
are allowed but will not be saved.
Side note: You do not need to load your subscriptions into Refermo manually as they are automatically added (and kept updated) by the system once your Paddle API keys are added to your account.
Example requests
POST
{
"identifier": "98729473294",
"email": "dan@danrowden.com"
}
POST
{
"identifier": "danr",
"email": "dan@gmail.com",
"code": "DAN",
"campaign": {
"id": "b7cfbd53"
},
"subscription": {
"id": 8263929
}
}
Response values
id
(string, 32 chars)
The unique Refermo ID for this member.identifier
(string, max 100 chars)
This is an unchanging, unique ID from your app.email
(string)first_name
(string ornull
)last_name
(string ornull
)code
(string, max 30 chars)stats
(dictionary)campaign
(dictionary ornull
)
A campaign object.subscription
(dictionary ornull
)
A subscription object.
Example response
HTTP 201 Created
{
"id": "44dc4d920bcfe2d3183ae33bc0f9b4ed",
"identifier": "3534543",
"email": "dan123@gmail.com",
"first_name": null,
"last_name": null,
"code": "4QE39VDA",
"stats": {
"link_clicks": 0,
"referrals": 0,
"conversions": 0,
"credit_earned": "0.00",
"commission_earned": "0.00",
"currency": "USD"
},
"campaign": {
"id": "1ba89be6",
"name": "Referrals",
"allows_credit": true,
"credit_amount": "10.00",
"credit_currency": "USD"
},
"subscription": null
}
Errors
If you pass a non-unique identifier
or email
value, the endpoint will return a HTTP 400
response with a corresponding error message.
HTTP 400 Bad Request
{
"email": [
"The email address dan124@gmail.com is already in use. Please choose another email address for this member."
]
}
If you provide a campaign or subscription ID that does not exist, you will also get a HTTP 400
error.
HTTP 400 Bad Request
{
"campaign": [
"Campaign badcampaignid could not be found."
]
}
Update a member
PATCH https://api.refermo.co/v1/members/[id]/
Request parameters
id
The member's Refermo ID.
Request values
All attributes are optional when updating.
identifier
(string, max 100 chars)
A unique identifier for this user in your app. Could be a user ID, username or email address. This value should be something that never changes in your app.email
(string)
The email address of this member. Refermo uses this to contact your members about rewards or their account.first_name
(string, max 50 chars)last_name
(string, max 50 chars)code
(string, max 30 chars)
A unique code used in a member's referral link, likeyourdomain.com/?via=CODE
.campaign
(dictionary)
Use a dictionary like{"id": "[campaign_id]"}
to either add a member to a campaign or move them to a different campaign.id
is the campaign's Refermo ID.
To remove a member from a campaign, simply setcampaign
tonull
.
Note: members cannot earn rewards if they're not in a campaign!subscription
(dictionary)
Use a dictionary like{"id": "[subscription_id]"}
to either attach a subscription to this member.id
is the subscription's ID in Paddle, which is carried over into Refermo to make things super easy.
To remove a subscription from a member, simply setsubscription
tonull
.
Example requests
PATCH
{
"email": "dan@danrowden.com"
}
PATCH
{
"code": "NEWCODE",
"campaign": null,
"subscription": {
"id": 8336392
}
}
Response values
id
(string, 32 chars)
The unique Refermo ID for this member.identifier
(string, max 100 chars)email
(string)first_name
(string ornull
)last_name
(string ornull
)code
(string, max 30 chars)stats
(dictionary)campaign
(dictionary ornull
)
A campaign object.subscription
(dictionary ornull
)
A subscription object.
Example response
HTTP 201 Created
{
"id": "44dc4d920bcfe2d3183ae33bc0f9b4ed",
"identifier": "3534543",
"email": "dan123@gmail.com",
"first_name": null,
"last_name": null,
"code": "4QE39VDA",
"stats": {
"link_clicks": 0,
"referrals": 0,
"conversions": 0,
"credit_earned": "0.00",
"commission_earned": "0.00",
"currency": "USD"
},
"campaign": {
"id": "1ba89be6",
"name": "Referrals",
"allows_credit": true,
"credit_amount": "10.00",
"credit_currency": "USD"
},
"link_clicks": 0,
"subscription": null
}
Errors
If you pass a non-unique identifier
or email
value, the endpoint will return a HTTP 400
response with a corresponding error message.
HTTP 400 Bad Request
{
"email": [
"The email address dan124@gmail.com is already in use. Please choose another email address for this member."
]
}
If you provide a campaign or subscription ID that does not exist, you will also get a HTTP 400
error.
HTTP 400 Bad Request
{
"campaign": [
"Campaign badcampaignid could not be found."
]
}
Delete a member
DELETE https://api.refermo.co/v1/members/[id]/
Request parameters
id
The member's Refermo ID.
Response values
None.
Example response
HTTP 204 No Content