Alpha API Documentation

Recipients

Retrieving recipient information

GET /recipients/{Recipient: ID, Email, Public key}

This endpoint returns information on a recipient. The ID field can be used for further requests.

JSON
HTTP Status 200 OK 
{
  "id": "OLMKne7Y3N",
  "email": "wallace@example.com",
  "public_key": "dQw4w9WgXcQ"
  "active": 1,
  "locale": null,
  "firstname": "Wallace",
  "surname": "Wensleydale",
  "company": "Anti-Pesto Pest Control",
  "address1": "62 West Wallaby Street",
  "address2": null,
  "address3": null,
  "town": "Wigan",
  "postcode": "WG7 7FU",
  "country_code": "gb",
  "telephone": "01942 992143",
  "del_firstname": null,
  "del_surname": null,
  "del_company": null,
  "del_address1": null,
  "del_address2": null,
  "del_address3": null,
  "del_town": null,
  "del_postcode": null,
  "del_country_code": null,
  "del_telephone": null,
  "created_at": "2020-01-24 15:14:05",
  "updated_at": "2020-03-24 22:20:10",
  "balance": 234
}

If the customer does not exist, you will instead get: (Note the HTTP Status code)

JSON
HTTP Status 404 Not Found 
{
  "message": ""
}

Creating a new recipient

POST /recipients/

To create a new recipient, make a PUT request to the above endpoint, with the information formatted in JSON in the Body content.

These are the fields available
Property Required? Example Notes
emailRequiredwallace@example.comMust be unique within your store
public_keydQw4w9WgXcQMust be unique within your store
firstnameRequiredWallace
surnameRequiredWensleydale
companyAnti-Pesto Pest Control
address162 West Wallaby Street
address2Floor 2
address3Unit 123
townWigan
postcodeWG7 7FU
telephone01942 992143
country_codegbLowercase ISO 3166-1 alpha-2. If not specified, defaults to default reward store setting.
del_firstnameWallace
del_surnameWensleydale
del_companyAnti-Pesto Pest Control
del_address162 West Wallaby Street
del_address2Floor 2
del_address3Unit 123
del_townWigan
del_postcodeWG7 7FU
del_telephone01942 992143
del_country_codegbLowercase ISO 3166-1 alpha-2

ISO 3166-1 reference

Please note:
  • The ISO 3166-1 alpha-2 code for the United Kingdom is gb, not uk.
  • The Channel Islands (Jersey, Guernsey) and the Isle of Man are not part of the UK, and have their own ISO 3166-1 alpha-2 codes. (JE, GG, IM)

Use the template below as an example. If there is no data for an item, simply don't include the property.

JSON
Body content 
{
  "email": "wallace@example.com",
  "firstname": "Wallace",
  "surname": "Wensleydale",
  "company": "Anti-Pesto Pest Control",
  "address1": "62 West Wallaby Street",
  "town": "Wigan",
  "postcode": "WG7 7FU",
  "telephone": "01942 992143",
  "country_code": "gb"
}

If successful, you'll receive a response similar to the Retrieving recipient information response.

If there is something wrong with the data provided, you'll get a response like below:

JSON
HTTP Status 422 Unprocessable Entity 
{
  "message": "The given data was invalid.",
  "errors": {
      "email": [
          "The email field is required."
      ],
      "firstname": [
          "The firstname field is required."
      ],
      "surname": [
          "The surname field is required."
      ],
      "address1": [
          "The address1 field is required."
      ],
      "town": [
          "The town field is required."
      ],
      "postcode": [
          "The postcode field is required."
      ],
      "country_code": [
          "The selected country code is invalid."
      ]
  }
}

Update a recipient

PUT /recipients/{Recipient: ID, Email, Public key}

Update a recipient by specifying the fields you wish to change. Fields are described in the Create Recipient section above.

Use the template below as an example. If there is no data for an item, simply don't include the property.

JSON
Body content 
{
    "company": "Top Bun Traditional Bakery",
    "telephone": "01942 112142"
}