Campaigns are groups of settings, rewards and members within your referral programme. On all plans but the Starter plan you can have multiple campaigns, so you can give different rewards to different groups of users.

List campaigns

GET https://api.refermo.co/v1/campaigns/

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.

Campaign data

  • id (string, 8 chars)
    The unique ID for this campaign.
  • name (string, max 100 chars)
    The private, internal name you've named each campaign.
  • allows_credit (true or false)
    If credit is offered as a reward to referrers.
  • credit_amount (decimal as a string)
    The amount of credit referrers get added to their subscription per referral.
  • credit_currency (string, 3 chars)
    The currency used for credit.

Example response

HTTP 200 OK
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "1ba89be6",
      "name": "Commission",
      "allows_credit": true,
      "credit_amount": "10.00",
      "credit_currency": "USD"
    },
    {
      "id": "4d0e29b3",
      "name": "Referrals",
      "allows_credit": true,
      "credit_amount": "15.00",
      "credit_currency": "USD"
    }
  ]
}

Retrieve a campaign

GET https://api.refermo.co/v1/campaigns/[id]/

Request parameters

  • id
    The campaign's Refermo ID.

Response values

  • id (string, 8 chars)
    The unique ID for this campaign.
  • name (string, max 100 chars)
    The private, internal name you've named each campaign.
  • allows_credit (true or false)
    If credit is offered as a reward to referrers.
  • credit_amount (decimal as a string)
    The amount of credit referrers get added to their subscription per referral.
  • credit_currency (string, 3 chars)
    The currency used for credit.

Example response

HTTP 200 OK
{
  "id": "4d0e29b3",
  "name": "Referrals",
  "allows_credit": true,
  "credit_amount": "15.00",
  "credit_currency": "USD"
}

Errors

If a campaign cannot be found, the endpoint will return a HTTP 404 response with an error message.

HTTP 404 Not Found
{
  "detail": "Not found."
}

Create a campaign

POST https://api.refermo.co/v1/campaigns/

Request parameters

  • None

Request values

  • name (string, max 100 chars) required
    The private, internal name for a campaign. This must be unique in your account.
  • allows_credit (true or false) default false
    If credit is offered as a reward to referrers.
  • credit_amount (decimal as a string) default 0.00
    The amount of credit referrers get added to their subscription per referral.
  • credit_currency (string, 3 chars) default USD
    The currency used for credit.

Example request

POST
{
  "name": "Referrals",
  "allows_credit": true,
  "credit_amount": "15.00",
  "credit_currency": "USD"
}

Response values

  • id (string, 8 chars)
    The unique ID for this campaign.
  • name (string, max 100 chars)
    The private, internal name you've named each campaign.
  • allows_credit (true or false)
    If credit is offered as a reward to referrers.
  • credit_amount (decimal as a string)
    The amount of credit referrers get added to their subscription per referral.
  • credit_currency (string, 3 chars)
    The currency used for credit.

Example response

HTTP 201 Created
{
  "id": "4d0e29b3",
  "name": "Referrals",
  "allows_credit": true,
  "credit_amount": "15.00",
  "credit_currency": "USD"
}

Errors

If you pass a non-unique name value, the endpoint will return a HTTP 400 response with an error message.

HTTP 400 Bad Request
{
  "name": [
    "The name Referrals is already in use. Please choose another name for this campaign."
  ]
}

Update a campaign

PATCH https://api.refermo.co/v1/campaigns/[id]/

Request parameters

  • id
    The campaign's Refermo ID.

Request values

All attributes are optional when updating.

  • name (string, max 100 chars)
    The private, internal name for a campaign.
  • allows_credit (true or false)
    If credit is offered as a reward to referrers.
  • credit_amount (decimal as a string)
    The amount of credit referrers get added to their subscription per referral.
  • credit_currency (string, 3 chars)
    The currency used for credit.

Example request

PATCH
{
    "name": "New name for this campaign"
}

Response values

  • id (string, 8 chars)
    The unique ID for this campaign.
  • name (string, max 100 chars)
    The private, internal name you've named each campaign.
  • allows_credit (true or false)
    If credit is offered as a reward to referrers.
  • credit_amount (decimal as a string)
    The amount of credit referrers get added to their subscription per referral.
  • credit_currency (string, 3 chars)
    The currency used for credit.

Example response

HTTP 200 OK
{
  "id": "4d0e29b3",
  "name": "Referrals",
  "allows_credit": true,
  "credit_amount": "15.00",
  "credit_currency": "USD"
}

Errors

If a campaign cannot be found, the endpoint will return a HTTP 404 response with an error message.

HTTP 404 Not Found
{
  "detail": "Not found."
}

If you pass an incorrect value, the endpoint will return a HTTP 400 response with an error message for each key and a list of error messages for each.

HTTP 400 Bad Request
{
  "credit_amount": [
    "A valid number is required."
  ]
}

Delete a campaign

DELETE https://api.refermo.co/v1/campaigns/[id]/

Request parameters

  • id
    The campaign's Refermo ID.

Response values

None.

Example response

HTTP 204 No Content

Errors

If a campaign cannot be found, the endpoint will return a HTTP 404 response with an error message.

HTTP 404 Not Found
{
  "detail": "Not found."
}