NAV Navbar
shell http

Overview

Base URL:

https://api.referrizer.com

Welcome to Referrizer API! The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, add token to Authorization header:

  -H 'Authorization: Bearer {apiToken}'
  Authorization: Bearer {apiToken}

An access token is required when making API requests. The access token should be supplied by using an HTTP header:

Authorization: Bearer {apiToken}

Your API token is placed inside backend on Apps / Integration page.

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size up to 100 with the ?perPage parameter.

GET /contacts?page=2&perPage=100

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

The total number of resources is always included in the X-Total-Count HTTP header.

Timestamps and timezones

All timestamps are represented in ISO 8601 format:

YYYY-MM-DDTHH:MM:SS.SSSZ

All timestamps are returned in UTC.

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON.

The errorCode parameter will indicate a CAPS_CASE constant error code that you can programmatically consume to make resolution decisions from. The message parameter will indicate a human-readable description of the error.

HTTP CODE ERROR CODE
400 MISSING_REQUIRED_FIELD
400 RESOURCE_ALREADY_EXISTS
400 CONTACT_ALREADY_CHECKED_IN
400 NOT_UNIQUE
400 ILLEGAL_ARGUMENT
400 INSUFFICIENT_LOYALTY_POINTS
400 NOT_AVAILABLE
401 MISSING_TOKEN
401 INVALID_TOKEN
404 RESOURCE_NOT_FOUND
429 TOO_MANY_REQUESTS

Contacts

Contacts allow you to send automated messages and to track visits or engagement that is associated with the same customer when pulled to the Referrizer system. The API allows you to create, update and delete your contacts. You can retrieve individual contacts as well as a list of all your contacts.

The contact object

Example response:

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 430

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}
Attribute Description
id
String
Unique identifier for the object.
firstName
String
Contact's first name.
lastName
String
Contact's last name.
phone
String
Phone number. This field is required if there is no email address provided.
email
String
Email address. This field is required if there is no phone number provided.
birthDate
String
Birth date in timestamp.
registrationDate
String
Date when contact is created.
firstVisitDate
String
Date of the first visit (first check in).
lastVisitDate
String
Date of the last visit (last check in).
visitsCount
Number
Total number of visits.
loyaltyPointsCount
Number
Number of loyalty points.
type
String
Contact's type. Can be ACTIVE, PASSIVE, POTENTIAL or OTHER.
description
String
An arbitrary string that you can attach to a contact. It is displayed in the Contact details page.
labels
Array
Array of contact's labels.

Create a contact

POST /v1/contacts

Example request:

$ curl 'https://api.referrizer.com/v1/contacts' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDU5NiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.uSU2xnW3MiNsDADwMGq-M_S7XTPVuMiHwJ5kqH5mgdzaQ97GDokkD06ul_f9KzBcTmNq3Q3H5vJU493LbRkVYw' \
    -H 'Accept: application/json' \
    -d '{
  "firstName" : "Joe",
  "lastName" : "Doe",
  "phone" : "19547806028",
  "type" : "POTENTIAL"
}'
POST /v1/contacts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDU5NiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.uSU2xnW3MiNsDADwMGq-M_S7XTPVuMiHwJ5kqH5mgdzaQ97GDokkD06ul_f9KzBcTmNq3Q3H5vJU493LbRkVYw
Accept: application/json
Host: api.referrizer.com
Content-Length: 98

{
  "firstName" : "Joe",
  "lastName" : "Doe",
  "phone" : "19547806028",
  "type" : "POTENTIAL"
}

Example response:

{
  "id" : "3f1dd76b2b1ee5737abf631bdeb4014f",
  "firstName" : "Joe",
  "lastName" : "Doe",
  "phone" : "19547806028",
  "email" : null,
  "birthDate" : null,
  "registrationDate" : "2019-03-20T01:23:18.000Z",
  "firstVisitDate" : null,
  "lastVisitDate" : null,
  "visitsCount" : 0,
  "loyaltyPointsCount" : 0,
  "type" : "POTENTIAL",
  "description" : null,
  "labels" : [ ]
}
HTTP/1.1 201 Created
Location: https://api.referrizer.com/v1/contacts/3f1dd76b2b1ee5737abf631bdeb4014f
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 378

{
  "id" : "3f1dd76b2b1ee5737abf631bdeb4014f",
  "firstName" : "Joe",
  "lastName" : "Doe",
  "phone" : "19547806028",
  "email" : null,
  "birthDate" : null,
  "registrationDate" : "2019-03-20T01:23:18.000Z",
  "firstVisitDate" : null,
  "lastVisitDate" : null,
  "visitsCount" : 0,
  "loyaltyPointsCount" : 0,
  "type" : "POTENTIAL",
  "description" : null,
  "labels" : [ ]
}

Creates a new contact object.

Request arguments

Argument Description
firstName
String
optional
Contact's first name.
lastName
String
optional
Contact's last name.
phone
String
required
Phone number. This field is required if there is no email address provided.
email
String
required
Email address. This field is required if there is no phone number provided.
birthDate
String
optional
Birth date in timestamp.
type
String
optional
Contact's type. Can be ACTIVE, PASSIVE, POTENTIAL or OTHER. Default value is ACTIVE.
description
String
optional
An arbitrary string that you can attach to a contact. It is displayed in the Contact details page.
labels
Array
optional
Array of contact's labels.
shouldSendNotification
Boolean
optional
Option to send registration notification (email/text) to the contact, if email/phone is provided. By default, notification will not be sent. To see or change text template visit Loyalty settings page. Email template can be changed on Email templates page.

Returns

Returns a contact object if the call succeeded. If neither the phone number nor the email address has been provided, the call will return an error. If a contact with provided phone/email alredy exists, the call will return an error.

Retrieve a contact

Retrieves the details of an existing contact. You only need to supply the unique contact identifier that was returned upon contact creation.

GET /v1/contacts/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/contacts/0918377d2949a9bc3f86f0e66e721e7e' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDYwMiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.4PFHB5Y7saerGGJBdD3f7gnhQCBwoskm5NLr-vq6SiNmRs8g4sA-WYpxloaG0M9K6axdzASZl_WSpZ7A0E8dxA' \
    -H 'Accept: application/json'
GET /v1/contacts/0918377d2949a9bc3f86f0e66e721e7e HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDYwMiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.4PFHB5Y7saerGGJBdD3f7gnhQCBwoskm5NLr-vq6SiNmRs8g4sA-WYpxloaG0M9K6axdzASZl_WSpZ7A0E8dxA
Accept: application/json
Host: api.referrizer.com

Example response:

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 430

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}

Path parameters

Parameter Description
id Unique identifier for the contact.

Returns

Returns a contact object if a valid identifier was provided.

Update a contact

PUT /v1/contacts/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/contacts/0918377d2949a9bc3f86f0e66e721e7e' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDYwMCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.0BqNBIFCVn7CvvPtU5zOOLIIOAy8IVp4vw1WfRri4PYwGLoe1fWx3FOQBZDr3prXDhUC5IDQHrl7FkgYMCC5bw' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : "15417543049",
  "email" : "jack.king@email.com",
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "labels" : [ ]
}'
PUT /v1/contacts/0918377d2949a9bc3f86f0e66e721e7e HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDYwMCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.0BqNBIFCVn7CvvPtU5zOOLIIOAy8IVp4vw1WfRri4PYwGLoe1fWx3FOQBZDr3prXDhUC5IDQHrl7FkgYMCC5bw
Accept: application/json
Host: api.referrizer.com
Content-Length: 393

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : "15417543049",
  "email" : "jack.king@email.com",
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "labels" : [ ]
}

Example response:

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : "15417543049",
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 439

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : "15417543049",
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}

Updates the specified contact by setting the values of the parameters passed. Any parameters not provided will be set to null. This request accepts mostly the same arguments as the contact creation call. Note that you can pass whole object returned from GET request, non-updatable arguments will be ignored.

Path parameters

Parameter Description
id Unique identifier for the contact.

Request arguments

Argument Description
firstName
String
optional
Contact's first name.
lastName
String
optional
Contact's last name.
phone
String
required
Phone number. This field is required if there is no email address provided.
email
String
required
Email address. This field is required if there is no phone number provided.
birthDate
String
optional
Birth date in timestamp.
type
String
optional
Contact's type. Can be ACTIVE, PASSIVE, POTENTIAL or OTHER. Default value is ACTIVE.
description
String
optional
An arbitrary string that you can attach to a contact. It is displayed in the Contact details page.
labels
Array
optional
Array of contact's labels.

Returns

Returns the contact object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid type).

Delete a contact

Permanently deletes a contact. It cannot be undone.

DELETE /v1/contacts/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/contacts/0918377d2949a9bc3f86f0e66e721e7e' -i -X DELETE \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDU5OSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.AdbamSqOEUlNIJISdVrP64pWFZ6G7100kVuSV_OvFOq4cmqw8dAwekn2mPnLrNP0BSXP9S-otT-3uDxpIukc9g' \
    -H 'Accept: application/json'
DELETE /v1/contacts/0918377d2949a9bc3f86f0e66e721e7e HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDU5OSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.AdbamSqOEUlNIJISdVrP64pWFZ6G7100kVuSV_OvFOq4cmqw8dAwekn2mPnLrNP0BSXP9S-otT-3uDxpIukc9g
Accept: application/json
Host: api.referrizer.com

Example response:

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 430

{
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
}

Path parameters

Parameter Description
id Unique identifier for the contact.

Returns

Returns an deleted object. If the contact ID does not exist, this call returns an error.

List all contacts

Returns a list of your contacts. The contacts are returned sorted by registration date, with the most recent contacts appearing first.

GET /v1/contacts

Example request:

$ curl 'https://api.referrizer.com/v1/contacts?perPage=2' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDYwMywidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.XbWcW-j4SF4ewlHYbTUdUfjfVp9w_rDtYhvdwXr15uno0lXvnzsOOg4KZyPkbhmZ_dxVfwy-BcNA1aivT1Q3yA' \
    -H 'Accept: application/json'
GET /v1/contacts?perPage=2 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDYwMywidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.XbWcW-j4SF4ewlHYbTUdUfjfVp9w_rDtYhvdwXr15uno0lXvnzsOOg4KZyPkbhmZ_dxVfwy-BcNA1aivT1Q3yA
Accept: application/json
Host: api.referrizer.com

Example response:

[ {
  "id" : "7745590a7cd4596cad4980d3c62449f7",
  "firstName" : "Zoe",
  "lastName" : "Smith",
  "phone" : "19541112222",
  "email" : null,
  "birthDate" : "1994-06-17T04:00:00.000Z",
  "registrationDate" : "2018-10-23T21:08:33.000Z",
  "firstVisitDate" : null,
  "lastVisitDate" : null,
  "visitsCount" : 0,
  "loyaltyPointsCount" : 0,
  "type" : "OTHER",
  "description" : null,
  "labels" : [ ]
}, {
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
} ]
HTTP/1.1 200 OK
X-Total-Count: 2
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 834

[ {
  "id" : "7745590a7cd4596cad4980d3c62449f7",
  "firstName" : "Zoe",
  "lastName" : "Smith",
  "phone" : "19541112222",
  "email" : null,
  "birthDate" : "1994-06-17T04:00:00.000Z",
  "registrationDate" : "2018-10-23T21:08:33.000Z",
  "firstVisitDate" : null,
  "lastVisitDate" : null,
  "visitsCount" : 0,
  "loyaltyPointsCount" : 0,
  "type" : "OTHER",
  "description" : null,
  "labels" : [ ]
}, {
  "id" : "0918377d2949a9bc3f86f0e66e721e7e",
  "firstName" : "Jack",
  "lastName" : "King",
  "phone" : null,
  "email" : "jack.king@email.com",
  "birthDate" : null,
  "registrationDate" : "2018-08-11T19:45:38.000Z",
  "firstVisitDate" : "2018-08-30T21:12:08.000Z",
  "lastVisitDate" : "2018-09-10T17:50:49.000Z",
  "visitsCount" : 2,
  "loyaltyPointsCount" : 10,
  "type" : "ACTIVE",
  "description" : null,
  "labels" : [ ]
} ]

Request parameters

Parameter Description
email
optional
A filter on the list based on the contact’s email field.
phone
optional
A filter on the list based on the contact’s phone field. You should not provide more than one filter argument.
page
optional
Current page of the collection. Default is 1.
perPage
optional
Maximum number of items to be returned in result set. Default is 30.

Returns

An array of up to perPage contacts. Passing an optional phone or email will result in filtering to contacts with only that exact phone/email. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty. This request should never return an error.

Visits

Visits can be described as Appointments, Classes or Sessions attended. This will allow the push or pull of information based on attendance or action.

The visit object

Example response:

{
  "id" : "ddd73fd6d526c547299779a7db2f00fc",
  "date" : "2018-08-30T21:12:08.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 154

{
  "id" : "ddd73fd6d526c547299779a7db2f00fc",
  "date" : "2018-08-30T21:12:08.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}
Attribute Description
id
String
Unique identifier for the object.
date
String
Date of the visit.
points
Number
Number of earned loyalty points.
contactId
String
The ID of the contact.

Create a visit

POST /v1/visits

Example request:

$ curl 'https://api.referrizer.com/v1/visits' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDY2OCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.nyE-h-XiY9TXAVaezCrbuU_hgYquC4lzmeXFMLjBCvTvxR18b6k3R5mjUVNXGwhFId96TFiBmB0PlAEaVkzS5g' \
    -H 'Accept: application/json' \
    -d '{
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}'
POST /v1/visits HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDY2OCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.nyE-h-XiY9TXAVaezCrbuU_hgYquC4lzmeXFMLjBCvTvxR18b6k3R5mjUVNXGwhFId96TFiBmB0PlAEaVkzS5g
Accept: application/json
Host: api.referrizer.com
Content-Length: 54

{
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}

Example response:

{
  "id" : "19a3aac7d2ba8ba5ea730a92fa066d50",
  "date" : "2019-03-20T01:24:29.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e",
  "checkinSource" : "Checkin from API"
}
HTTP/1.1 201 Created
Location: https://api.referrizer.com/v1/visits/19a3aac7d2ba8ba5ea730a92fa066d50
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 194

{
  "id" : "19a3aac7d2ba8ba5ea730a92fa066d50",
  "date" : "2019-03-20T01:24:29.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e",
  "checkinSource" : "Checkin from API"
}

Creates a new visit object.

Request arguments

Argument Description
contactId
String
required
The ID of an existing contact that will get visit in this request.
points
Number
optional
Loyalty points to be earned. If not provided, the number of earned points will depend on your Loyalty settings.

Returns

Returns a visit object if the call succeeded. If contact's ID has not been provided, the call will return an error. If a contact with provided ID does not exist, the call will return an error.

Retrieve a visit

Retrieves the details of an visit. You only need to supply the unique visit identifier that was returned upon visit creation.

GET /v1/visits/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/visits/ddd73fd6d526c547299779a7db2f00fc' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDY3MCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.sFT5NFEb0QbP2sCaNdujUTA4gX6umnZfxKSQ4bwgRUS2jktnILpPlmG9PtWAPVmePhbjOaplkZl36E_wWpED0A' \
    -H 'Accept: application/json'
GET /v1/visits/ddd73fd6d526c547299779a7db2f00fc HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDY3MCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.sFT5NFEb0QbP2sCaNdujUTA4gX6umnZfxKSQ4bwgRUS2jktnILpPlmG9PtWAPVmePhbjOaplkZl36E_wWpED0A
Accept: application/json
Host: api.referrizer.com

Example response:

{
  "id" : "ddd73fd6d526c547299779a7db2f00fc",
  "date" : "2018-08-30T21:12:08.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 154

{
  "id" : "ddd73fd6d526c547299779a7db2f00fc",
  "date" : "2018-08-30T21:12:08.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}

Path parameters

Parameter Description
id Unique identifier for the visit.

Returns

Returns a visit object if a valid identifier was provided.

List all visits

Returns a list of your visits. The visit are returned sorted by visit date, with the most recent visits appearing first.

GET /v1/visits

Example request:

$ curl 'https://api.referrizer.com/v1/visits?contactId=0918377d2949a9bc3f86f0e66e721e7e' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDY3MSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.va2FtmPLhsqczLrYgCDbf-YBhkYdTjSbky9g13kq3aokt_DzLIs_4dkvRqqcOxcGMX5DrmEZHl5Zb8aGYAKPzg' \
    -H 'Accept: application/json'
GET /v1/visits?contactId=0918377d2949a9bc3f86f0e66e721e7e HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDY3MSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.va2FtmPLhsqczLrYgCDbf-YBhkYdTjSbky9g13kq3aokt_DzLIs_4dkvRqqcOxcGMX5DrmEZHl5Zb8aGYAKPzg
Accept: application/json
Host: api.referrizer.com

Example response:

[ {
  "id" : "9d1e48c5864e29c8a059e6811d7305f5",
  "date" : "2018-09-10T17:50:49.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}, {
  "id" : "ddd73fd6d526c547299779a7db2f00fc",
  "date" : "2018-08-30T21:12:08.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
} ]
HTTP/1.1 200 OK
X-Total-Count: 2
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 314

[ {
  "id" : "9d1e48c5864e29c8a059e6811d7305f5",
  "date" : "2018-09-10T17:50:49.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
}, {
  "id" : "ddd73fd6d526c547299779a7db2f00fc",
  "date" : "2018-08-30T21:12:08.000Z",
  "points" : 5,
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e"
} ]

Request parameters

Parameter Description
contactId
optional
A filter on the list based on the contact’s ID.
page
optional
Current page of the collection. Default is 1.
perPage
optional
Maximum number of items to be returned in result set. Default is 30.

Returns

An array of up to perPage visits. Passing an optional contactId will result in filtering visits only from that contact. Each entry in the array is a separate visit object. If no more visits are available, the resulting array will be empty. This request should never return an error.

Labels

Labels can be described as specific groupings. This will allow Contacts to be filtered together based on titles or tags assigned to them.

The label object

Example response:

{
  "id" : "80288f29e22cfd82db0167caac852301",
  "name" : "VIP",
  "color" : "LIME"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "id" : "80288f29e22cfd82db0167caac852301",
  "name" : "VIP",
  "color" : "LIME"
}
Attribute Description
id
String
Unique identifier for the object.
name
String
Name of the label.
color
String
Label color.

Create a label

POST /v1/labels

Example request:

$ curl 'https://api.referrizer.com/v1/labels' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDM3NCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.-P5oq7zY4auKMbSfVxzRGaknnM1_8EreZtw3gSwW4BaijAmjUrWgb168rzAmkE_jH8q39xdg8e7vWDG6JEdlDg' \
    -H 'Accept: application/json' \
    -d '{
  "name" : "Win back",
  "color" : "RED"
}'
POST /v1/labels HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDM3NCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.-P5oq7zY4auKMbSfVxzRGaknnM1_8EreZtw3gSwW4BaijAmjUrWgb168rzAmkE_jH8q39xdg8e7vWDG6JEdlDg
Accept: application/json
Host: api.referrizer.com
Content-Length: 44

{
  "name" : "Win back",
  "color" : "RED"
}

Example response:

{
  "id" : "5b2a38b6cce6325238c326de964a0364",
  "name" : "Win back",
  "color" : "RED"
}
HTTP/1.1 201 Created
Location: https://api.referrizer.com/v1/labels/5b2a38b6cce6325238c326de964a0364
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 89

{
  "id" : "5b2a38b6cce6325238c326de964a0364",
  "name" : "Win back",
  "color" : "RED"
}

Creates a new label object.

Request arguments

Argument Description
name
String
required
Name of the label. Must be unique.
color
String
optional
Label color. Possible values are RED, PINK, PURPLE, DEEP_PURPLE, INDIGO, LIGHT_BLUE, CYAN, TEAL, LIME, AMBER, ORANGE, DEEP_ORANGE, BROWN, GREY or BLUE_GREY. Default is GREY.

Returns

Returns a label object if the call succeeded. If name has not been provided or label with given name already exists, the call will return an error. If a color code does not exist, the call will return an error.

Retrieve a label

Retrieves the details of an label. You only need to supply the unique visit identifier that was returned upon label creation.

GET /v1/labels/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/labels/80288f29e22cfd82db0167caac852301' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDM4MSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.aqV2i33yq_lrpm_NDO9vnutmUMw2RfMJdh1AQIjl5KVBMu-UshKFqwTkzypP7wJvuRfbfNONnKR3tUkcndKYBg' \
    -H 'Accept: application/json'
GET /v1/labels/80288f29e22cfd82db0167caac852301 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDM4MSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.aqV2i33yq_lrpm_NDO9vnutmUMw2RfMJdh1AQIjl5KVBMu-UshKFqwTkzypP7wJvuRfbfNONnKR3tUkcndKYBg
Accept: application/json
Host: api.referrizer.com

Example response:

{
  "id" : "80288f29e22cfd82db0167caac852301",
  "name" : "VIP",
  "color" : "LIME"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "id" : "80288f29e22cfd82db0167caac852301",
  "name" : "VIP",
  "color" : "LIME"
}

Path parameters

Parameter Description
id Unique identifier for the label.

Returns

Returns a label object if a valid identifier was provided.

List all label

Returns a list of your labels.

GET /v1/labels

Example request:

$ curl 'https://api.referrizer.com/v1/labels?perPage=2' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDM4MiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.OVsnaHbiusMPiXkMkxtwjrBgbnOgCaX35Ax-8ywC9QGUo8t-dovACYSD6MFBK7MU5dC2fbew0vGd3CtmdBwMlA' \
    -H 'Accept: application/json'
GET /v1/labels?perPage=2 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDM4MiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.OVsnaHbiusMPiXkMkxtwjrBgbnOgCaX35Ax-8ywC9QGUo8t-dovACYSD6MFBK7MU5dC2fbew0vGd3CtmdBwMlA
Accept: application/json
Host: api.referrizer.com

Example response:

[ {
  "id" : "59f85cb3b69468fa3a609c8efe3358cf",
  "name" : "Google contacts",
  "color" : "ORANGE"
}, {
  "id" : "80288f29e22cfd82db0167caac852301",
  "name" : "VIP",
  "color" : "LIME"
} ]
HTTP/1.1 200 OK
X-Total-Count: 3
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 190

[ {
  "id" : "59f85cb3b69468fa3a609c8efe3358cf",
  "name" : "Google contacts",
  "color" : "ORANGE"
}, {
  "id" : "80288f29e22cfd82db0167caac852301",
  "name" : "VIP",
  "color" : "LIME"
} ]

Request parameters

Parameter Description
page
optional
Current page of the collection. Default is 1.
perPage
optional
Maximum number of items to be returned in result set. Default is 30.

Returns

An array of up to perPage visits. Each entry in the array is a separate label object. If no more labels are available, the resulting array will be empty. This request should never return an error.

Loyalty rewards

A well-thought-out Loyalty Program helps drive repeat visits and purchase to the business. With the API you can create, retrieve, update and delete your loyalty rewards.

The loyalty reward object

Example response:

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : {
    "total" : 1000,
    "perContact" : null
  },
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 282

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : {
    "total" : 1000,
    "perContact" : null
  },
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}
Attribute Description
id
String
Unique identifier for the object.
title
String
Title of the loyalty reward.
points
Number
Reward's worth in loyalty points.
quantity.total
Number
Total quantity of the reward. If NULL, there is no limit.
quantity.perContact
Number
Quantity that represents how many times each contact (customer) can redeem the reward. If NULL, there is no limit.
available.total
Number
Total available of the reward. If NULL, there is no limit.
available.perContact
Number
Remaining availability for the contact. Returned only when contactId is provided. If NULL, there is no limit.
contactId
String
The ID of the contact.
startDate
String
Start date of loyalty reward.
expiredDate
String
Expiration date of loyalty reward.
expires
Boolean
Reward can expire or not

Create a loyalty reward

POST /v1/loyalty-rewards

Example request:

$ curl 'https://api.referrizer.com/v1/loyalty-rewards' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1MSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.Y99GHREXW8N_C8TteEfqv0UGA3uEXsmAWrFuWgiprxwqRSxPN2Z2UcDUGix7-5KnwOC5m9F0D_0m-YafY5NGIA' \
    -H 'Accept: application/json' \
    -d '{
  "title" : "Burrito",
  "points" : 10,
  "quantity" : {
    "total" : 500
  }
}'
POST /v1/loyalty-rewards HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1MSwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.Y99GHREXW8N_C8TteEfqv0UGA3uEXsmAWrFuWgiprxwqRSxPN2Z2UcDUGix7-5KnwOC5m9F0D_0m-YafY5NGIA
Accept: application/json
Host: api.referrizer.com
Content-Length: 82

{
  "title" : "Burrito",
  "points" : 10,
  "quantity" : {
    "total" : 500
  }
}

Example response:

{
  "id" : "65e010c4cb31819f2ce0884b8c2dbaf0",
  "title" : "Burrito",
  "points" : 10,
  "quantity" : {
    "total" : 500,
    "perContact" : null
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}
HTTP/1.1 201 Created
Location: https://api.referrizer.com/v1/loyalty-rewards/65e010c4cb31819f2ce0884b8c2dbaf0
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 241

{
  "id" : "65e010c4cb31819f2ce0884b8c2dbaf0",
  "title" : "Burrito",
  "points" : 10,
  "quantity" : {
    "total" : 500,
    "perContact" : null
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}

Creates a new loyalty reward object.

Request arguments

Argument Description
title
String
required
Title of the loyalty reward.
points
Number
required
Reward's worth in loyalty points.
quantity.total
Number
optional
Total quantity of the reward. By default, value will be NULL, i.e. unlimited.
quantity.perContact
Number
optional
Quantity that represents how many times each contact (customer) can redeem the reward. By default, value will be NULL, i.e. unlimited.
startDate
String
optional
Start date of loyalty reward.
expiredDate
String
optional
Expiration date of loyalty reward.
expires
Boolean
optional
Reward can expire or not

Returns

Returns a loyalty reward object if the call succeeded.

Retrieve a loyalty reward

Retrieves the details of a loyalty reward. You only need to supply the unique reward identifier that was returned upon reward creation.

GET /v1/loyalty-rewards/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1NywidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.59NGyKcliE-kf2KAfbdgLsJsZukFMF3fdMu9TeGyWZKSucSJqBVkquEGJHnDsMdHLIxF5EcSrSQ5ZxQErhhwLQ' \
    -H 'Accept: application/json'
GET /v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1NywidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.59NGyKcliE-kf2KAfbdgLsJsZukFMF3fdMu9TeGyWZKSucSJqBVkquEGJHnDsMdHLIxF5EcSrSQ5ZxQErhhwLQ
Accept: application/json
Host: api.referrizer.com

Example response:

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : {
    "total" : 1000,
    "perContact" : null
  },
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 282

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : {
    "total" : 1000,
    "perContact" : null
  },
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}

Path parameters

Parameter Description
id Unique identifier for the loyalty reward.

Request parameters

Parameter Description
contactId
optional
Loyalty reward availability per contact’s ID.

Returns

Returns a loyalty reward object if a valid identifier was provided. Passing an optional contactId will retrieve loyalty reward availability per contact - perContact

Update a loyalty reward

PUT /v1/loyalty-rewards/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1NiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.EnLO-cRUO23WXLuj_EQM4tco2cVbWSS1PFpUL5VQ0h_rES_cVQTQPyLE1hwNc67ht39i5gSCwnTeku00hFDL4Q' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 16,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : {
    "total" : 1000
  },
  "expires" : false
}'
PUT /v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1NiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.EnLO-cRUO23WXLuj_EQM4tco2cVbWSS1PFpUL5VQ0h_rES_cVQTQPyLE1hwNc67ht39i5gSCwnTeku00hFDL4Q
Accept: application/json
Host: api.referrizer.com
Content-Length: 211

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 16,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : {
    "total" : 1000
  },
  "expires" : false
}

Example response:

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 16,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 237

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 16,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}

Updates the specified loyalty reward by setting the values of the parameters passed. Any parameters not provided will be set to null. The reward's title is not updatable. Note that you can pass whole object returned from GET request, non-updatable arguments will be ignored.

Path parameters

Parameter Description
id Unique identifier for the loyalty reward.

Request arguments

Argument Description
points
Number
required
Reward's worth in loyalty points.
quantity.total
Number
optional
Total quantity of the reward. By default, value will be NULL, i.e. unlimited.
quantity.perContact
Number
optional
Quantity that represents how many times each contact (customer) can redeem the reward. By default, value will be NULL, i.e. unlimited.
startDate
String
optional
Start date of loyalty reward.
expiredDate
String
optional
Expiration date of loyalty reward.
expires
Boolean
optional
Reward can expire or not

Returns

Returns the loyalty reward object if the update succeeded. Returns an error if update parameters are invalid (e.g. negative points value).

Delete a loyalty reward

Permanently deletes a loyalty reward. It cannot be undone.

DELETE /v1/loyalty-rewards/{id}

Example request:

$ curl 'https://api.referrizer.com/v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8' -i -X DELETE \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1MiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.PuENk_epIHVdhvioCi4jYb4ZYfwELssSqV53ehvlCwOKEvcXR_KjfcZMoMCizbUvR2NGTkn81CFUd-bw74S3Uw' \
    -H 'Accept: application/json'
DELETE /v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1MiwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.PuENk_epIHVdhvioCi4jYb4ZYfwELssSqV53ehvlCwOKEvcXR_KjfcZMoMCizbUvR2NGTkn81CFUd-bw74S3Uw
Accept: application/json
Host: api.referrizer.com

Example response:

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 237

{
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
}

Path parameters

Parameter Description
id Unique identifier for the loyalty reward.

Returns

Returns an deleted object. If the loyalty reward ID does not exist, this call returns an error.

List all loyalty reward

Returns a list of your loyalty reward. The rewards are returned sorted by loyalty points, with the smaller rewards appearing first.

GET /v1/loyalty-rewards

Example request:

$ curl 'https://api.referrizer.com/v1/loyalty-rewards?perPage=2' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1OCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.9rZaFgxDol08cmEpdaA6gKaudp1l6s6Bf75gn_zCRKDVZfEUzcN3RB4n3S5R4C4VNZWX1VmuST9TvXADSuiIEg' \
    -H 'Accept: application/json'
GET /v1/loyalty-rewards?perPage=2 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1OCwidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.9rZaFgxDol08cmEpdaA6gKaudp1l6s6Bf75gn_zCRKDVZfEUzcN3RB4n3S5R4C4VNZWX1VmuST9TvXADSuiIEg
Accept: application/json
Host: api.referrizer.com

Example response:

[ {
  "id" : "315e5a9ca3b0eb3d4b20c59a91a2ba16",
  "title" : "Lemonade",
  "points" : 5,
  "quantity" : {
    "total" : null,
    "perContact" : null
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : null
}, {
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
} ]
HTTP/1.1 200 OK
X-Total-Count: 2
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 484

[ {
  "id" : "315e5a9ca3b0eb3d4b20c59a91a2ba16",
  "title" : "Lemonade",
  "points" : 5,
  "quantity" : {
    "total" : null,
    "perContact" : null
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : null
}, {
  "id" : "9ab93cbfaf2902db6c5fd7ee5ef3f8b8",
  "title" : "Tacos",
  "points" : 12,
  "quantity" : {
    "total" : 1000,
    "perContact" : 1
  },
  "available" : null,
  "startDate" : null,
  "expiredDate" : null,
  "expires" : false
} ]

Request parameters

Parameter Description
page
optional
Current page of the collection. Default is 1.
perPage
optional
Maximum number of items to be returned in result set. Default is 30.

Returns

An array of up to perPage rewards. Each entry in the array is a separate loyalty reward object. If no more rewards are available, the resulting array will be empty. This request should never return an error.

Redeem a loyalty reward

POST /v1/loyalty-rewards/{id}/redeem

Example request:

$ curl 'https://api.referrizer.com/v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8/redeem' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1MywidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.jG2Foex3hAyZ7c0ykP81p_vj8p-xSB_8ofjoRyNkIva35e0wiyRJhuth9jUiUKm38MyuMnWstVIUogSSsQmJog' \
    -H 'Accept: application/json' \
    -d '{
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e",
  "pin" : "0000"
}'
POST /v1/loyalty-rewards/9ab93cbfaf2902db6c5fd7ee5ef3f8b8/redeem HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIyNTUxYmE3NzM0ZjdiMzkwOWZkZmY1ZmI4NjUwMGE3YiIsImV4cCI6NDcwNjYzMDQ1MywidXNlcm5hbWUiOiJsYXphckByZWZlcnJpemVyLmNvbSJ9.jG2Foex3hAyZ7c0ykP81p_vj8p-xSB_8ofjoRyNkIva35e0wiyRJhuth9jUiUKm38MyuMnWstVIUogSSsQmJog
Accept: application/json
Host: api.referrizer.com
Content-Length: 72

{
  "contactId" : "0918377d2949a9bc3f86f0e66e721e7e",
  "pin" : "0000"
}

Example response:


HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Path parameters

Parameter Description
id Unique identifier for the loyalty reward.

Request arguments

Argument Description
contactId
String
required
The ID of an existing contact that will redeem reward.
pin
String
optional
Employee's PIN. It's required if you set it so in Loyalty Settings.
note
String
optional
An arbitrary string that you can attach to a transaction.

Returns

Returns status code 204 if the redemption succeeded.