Members

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, or null if there isn't one.
• previous (string)
  The URL for the previous page of results, or null 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 or null)
• last_name (string or null)
• code (string, max 30 chars)
• stats (dictionary)
• campaign (dictionary or null)
  A campaign object.
• subscription (dictionary or null)
  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 or null)
• last_name (string or null)
• code (string, max 30 chars)
• stats (dictionary)
• campaign (dictionary or null)
  A campaign object.
• subscription (dictionary or null)
  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, like yourdomain.com/?via=CODE.
  If you don't specifiy a code, Refermo will generate an 8-character random string of numbers and capital letters, like B6D389J5.
• 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 an HTTP 400 error (see below). Keys other than id 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 the id value.  The id 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 an HTTP 400 error (see below). Keys other than id 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 or null)
• last_name (string or null)
• code (string, max 30 chars)
• stats (dictionary)
• campaign (dictionary or null)
  A campaign object.
• subscription (dictionary or null)
  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, like yourdomain.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 set campaign to null .
  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 set subscription to null .

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 or null)
• last_name (string or null)
• code (string, max 30 chars)
• stats (dictionary)
• campaign (dictionary or null)
  A campaign object.
• subscription (dictionary or null)
  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