SHIFT72 API Documentation

API Key

Summary: Get the currently active System API Key

Authentication: X-Auth Admin

                      GET /services/users/v1/api_key

Description

Use this API to get the currently active System API Key. This API is only accessible to users who have the admin role.

Response Parameters

Parameter	Type	Description
api_key	string	The System API Key can be used as an x-auth-token.
active	bool	Whether the System API Key is active.

Examples

API Key Request

curl -i 'https://store.shift72.com/services/users/v1/api_key' \
  -H 'x-auth-token: a7499b7029d80791ff18834fec73aeef'

Response: Success

HttpStatus: 200
{  
  "api_key":"ak_production_fe294da38860440191a814a14d1470b0",
  "active":true
}

Response: Not Found

HttpStatus: 404
{
  "error":"No Api Key present"
}

Response: Unauthorized

HttpStatus: 401

API Key Update

Summary: Request a new System API Key

Authentication: X-Auth Admin

                      POST /services/users/v1/api_key

Description

Use this API to get a new System API Key. This deactivates the previously used System API Key. This API is only accessible to users who have the admin role.

Response Parameters

Returns API Key.

Examples

Request New API Key

curl -i 'https://store.shift72.com/services/users/v1/api_key' \
  -X POST \
  -H 'x-auth-token: a7499b7029d80791ff18834fec73aeef'

Response: Success

HttpStatus: 200
{  
  "api_key":"ak_production_fe294da38860440191a814a14d1470b0",
  "active":true
}

Response: Unauthorized

HttpStatus: 401

Bouncer

Summary: Check if the signed in user has admin permissions

Authentication: X-Auth Admin

                      GET /services/users/auth/bouncer

Description

Use this API if you want to check if the signed in user has the admin role. This is often used after the Sign In API call when accessing an admin area. The benefit of this is that if the user is not an administrator, bouncer will sign the user out and you can display an appropriate message about the user not being an administrator. Otherwise API calls that require admin access will return an HTTP response code of 401, Unauthorized, which is the same response as if the session has expired.

Response Parameters

Parameter	Type	Description
message	string	A message that provides more information about the response.

Examples

Check If User Is an Administrator

curl -i 'https://store.shift72.com/services/users/auth/bouncer' \
  -H 'x-auth-token: 4566778ab896d7390992d1fc2a484bce'

Response: Success

HttpStatus: 200
{  
  "message":"If you got this far, you are an admin"
}

Response: Unauthorized

HttpStatus: 401

Sign In

Summary: Sign in with a valid user

Authentication: None

                      POST /services/users/auth/sign_in

Description

Use this API to sign a user in with the provided email and password. The auth_token that is returned is required on all API requests that are noted with “Authentication: X-Auth”. If the user also has the admin role, then the x-auth-token can also be used with API requests that are noted with “Authentication: X-Auth Admin”. Use the Bouncer API if you need to confirm that a user has the admin role.

Request Parameters

Parameter	Type	Description
email	string	Required. Email address of the user.
password	string	Required. User’s password.
remember_me	bool	Optional. Requests a longer session expiry. Session will extended to 30 days.

Response Parameters

Returns User Details.

Examples

curl https://store.shift72.com/services/users/auth/sign_in \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{ "user": {
            "email": "user@example.com",
            "password": "passw0rd"
            }
        }'

curl https://store.shift72.com/services/users/auth/sign_in \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{ "user": {
            "email": "user@example.com",
            "password": "passw0rd",
            "remember_me": false }
        }'

Response: Success

HttpStatus: 200
{  
  "auth_token":"ea34011c0c0e434bf7fb8365cd9185ba",
  "account":{  
    "user_id":947,
    "email":"user@example.com",
    "name":"Joe",
    "dob":"2000-01-31",
    "gender":"male",
    "users":[  
      {  
        "id":947,
        "email":"user@example.com",
        "name":"Joe",
        "avatar_url":null,
        "access_code":null,
        "account_admin":true,
        "dob":"2000-01-31",
        "gender":"male"
      }
    ],
    "bypass_cache":false
  }
}

Response: Failure

HttpStatus: 422
{  
  "error":"Try again, your email or password is incorrect"
}

Sign Out

Summary: Sign a user out from their current session

Authentication: X-Auth

                      DELETE /services/users/auth/sign_out

Description

Use this API to sign a user out and end their current session.

Response Parameters

Parameter	Type	Description
success	bool	Set to true if user successfully signed out.

Examples

Sign Out Request

curl -i 'https://store.shift72.com/services/users/auth/sign_out' \
  -X DELETE \
  -H 'x-auth-token: ea72a67428e3dad909779542bb59fa02'

Response: Success

HttpStatus: 200
{  
  "success":true
}

Sign Up

Summary: Sign up a new user

Authentication: None

                      POST /services/users/auth/sign_up

Description

Use this API to create a new user with the supplied details. On successful registration the new user will be signed in and sent a welcome email.

Request Parameters

Parameter	Type	Description
name	string	Required. Name of the user.
email	string	Required. Email address of the user.
password	string	Required. User’s password.
dob	string	Optional. Date of birth in ISO 8601 date format.
gender	string	Optional. The user’s gender. Can be male, female or other.
email_opt_in	bool	Optional. True if the user has opted in to email marketing. Default is false.

Response Parameters

Returns user details.

Examples

curl -i 'https://store.shift72.com/services/users/auth/sign_up' \
  -X POST \
  -H 'content-type: application/json;charset=UTF-8' \
  -d '{ "user":{  
          "name":"Joe",
          "email":"user@example.com",
          "password":"password",
          "dob":"2000-01-31",
          "gender":"male"
        }
      }'

Response: Success

HttpStatus: 200
{  
  "auth_token":"59ce33d78c7f766815c3e8ddae4080e6",
  "account":{  
    "user_id":947,
    "email":"user@example.com",
    "name":"Joe",
    "dob":"2000-01-31",
    "gender":"male",
    "users":[  
      {  
        "id":947,
        "email":"user@example.com",
        "name":"Joe",
        "avatar_url":null,
        "access_code":null,
        "account_admin":true,
        "dob":"2000-01-31",
        "gender":"male"
      }
    ],
    "bypass_cache":false
  }
}

Response: Failure

HttpStatus: 422
{  
  "error":{  
    "email":[  
      "email address has already been taken"
    ]
  }
}

User Exists

Summary: Check if the email address is already used

Authentication: None

                      GET /services/users/auth/account_exists

Description

Check if an account is already registered with the specified email address, or an external_id as configured by a custom integration.

Query String Request Parameters

Parameter	Description
email	The user’s email address - URL encoded.

Response Parameters

Parameter	Type	Description
exists	bool	True if the account exists.

Examples

Check if Email Exists

curl -i 'https://store.shift72.com/services/users/auth/account_exists?email=me@example.com'

Check if Account exists using an external id

curl -i 'https://store.shift72.com/services/users/auth/account_exists?external_id=aaaaa'

Response: Success

HttpStatus: 200
{  
   "exists":true
}

Response: Missing Email

HttpStatus: 400
{
  "error": "Missing email address",
  "code": "missing_email"
}

Configuration

Summary: Request users configuration settings

Authentication: None

                      GET /services/users/v1/configuration

Description

Use this API to get the configuration settings for the Users service.

Response Parameters

Parameter	Type	Description
signup_dob	bool	Set to true if the sign up form should ask for date of birth.
signup_gender	bool	Set to true if the sign up form should ask for gender.
signup_dob_and_gender	bool	Deprecated. Set to true if the sign up form should ask for date of birth and gender.

Examples

Users Configuration Request

curl -i 'https://store.shift72.com/services/users/v1/configuration'

Response: Success

HttpStatus: 200
{  
  "signup_dob":"true",
  "signup_gender":"true"
}

Configuration (Admin)

Summary: Request admin configuration settings

Authentication: X-Auth Admin

                      GET /services/users/v1/configuration/private

Description

Use this API to get the configuration settings that can be changed by an administrator. These configuration settings may include private settings that are only visible to administrators. This API is only accessible to users who have the admin role.

Response Parameters

Parameter	Type	Description
signup_dob	bool	Set to true if the sign up form should ask for date of birth.
signup_gender	bool	Set to true if the sign up form should ask for gender.
required_dob	bool	Set to true if the sign up form requires date of birth as compulsory fields.
required_gender	bool	Set to true if the sign up form requires gender as compulsory fields.
signup_dob_and_gender	bool	Deprecated. Set to true if the sign up form should ask for date of birth and gender.
required_dob_and_gender	bool	Deprecated. Set to true if the sign up form should requires date of birth and gender as compulsory fields.

Examples

Admin Configuration Request

curl -i 'https://store.shift72.com/services/users/v1/configuration/private' \
  -H 'x-auth-token: e69600dfa1d670b59d78971477ea0618'

Response: Success

HttpStatus: 200
{  
  "required_dob":true,
  "required_gender":true,
  "signup_dob":true,
  "signup_gender":true
}

Response: Unauthorized

HttpStatus: 401

Configuration Update (Admin)

Summary: Update admin configuration settings

Authentication: X-Auth Admin

                      PATCH /services/users/v1/configuration/private

Description

Use this API to update the configuration settings for the site. These configuration settings may include private settings that are only visible to administrators. This API is only accessible to users who have the admin role.

Request Parameters

Parameter	Type	Description
signup_dob	bool	Set to true if the sign up form should ask for date of birth.
signup_gender	bool	Set to true if the sign up form should ask for gender.
required_dob	bool	Set to true if the sign up form requires date of birth as compulsory fields.
required_gender	bool	Set to true if the sign up form requires gender as compulsory fields.
signup_dob_and_gender	bool	Deprecated. Set to true if the sign up form should ask for date of birth and gender.
required_dob_and_gender	bool	Deprecated. Set to true if the sign up form should requires date of birth and gender as compulsory fields.

Response Parameters

Returns Configuration (Admin).

Examples

Update Field

curl -i 'https://store.shift72.com/services/meta/v1/configuration/private' \
  -X PATCH \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{ "signup_dob":true, "signup_gender": true }'

Response: Success

HttpStatus: 200
{  
  "required_dob":true,
  "required_gender":true,
  "signup_dob":true,
  "signup_gender": true  
}

Response: Key Doesn’t Exist

HttpStatus: 400
{
  "error":"Bad request, request contains invalid key."
}

Response: Unauthorized

HttpStatus: 401

Details

Summary: Get the user's details

Authentication: X-Auth

                      GET /services/users/detail/users

Description

Use this API to get the user details of the currently signed in user.

Response Parameters

Parameter	Type	Description
auth_token	string	The authorization token required for X-Auth API requests.
user_id	number	The user’s unique ID.
email	string	The user’s email address.
name	string	The user’s name.
avatar_url	string	Deprecated. A URL to an image. This is not used.
access_code	string	Deprecated. This is not used.
account_admin	bool	Deprecated. This is not used.
dob	string	Date of birth in ISO 8601 date format.
bypass_cache	bool	Some accounts can bypass the five-minute cache.
gender	string	The user’s gender. Can be male, female or other.

Examples

User Details Request

curl -i 'https://store.shift72.com/services/users/detail/users' \
     -H 'x-auth-token: e7ddfaf607c1b9f165500b312dc3d6d5'

Response: Success

HttpStatus: 200
{  
  "auth_token":"ea34011c0c0e434bf7fb8365cd9185ba",
  "account":{  
    "user_id":947,
    "email":"user@example.com",
    "name":"Joe",
    "dob":"2000-01-31",
    "gender":"male",
    "users":[  
      {  
        "id":947,
        "email":"user@example.com",
        "name":"Joe",
        "avatar_url":null,
        "access_code":null,
        "account_admin":true,
        "dob":"2000-01-31",
        "gender":"male"
      }
    ],
    "bypass_cache":false
  }
}

Response: Unauthorized

HttpStatus: 401

Details (Admin)

Summary: Get the user's details as an administrator

Authentication: X-Auth Admin

                      GET /services/users/users/[user_id]/show

Description

Use this API if you are an administrator and want to get the user details of a specific user. This API is only accessible to users who have the admin role. The response is different to the Details API in that it includes information that is only available to administrators, such as the date the user last signed in.

Response Parameters

Parameter	Type	Description
id	number	The user’s unique ID.
name	string	The user’s name.
email	string	The user’s email address.
status	string	Either ‘suspended’ or ‘active’. Null is the same as active.
last_sign_in	string	ISO 8601 format of the date and time the user last signed in.
sign_in_count	number	The number of times the user has signed in.
roles_ids	number	An array of roles where 1 = admin. Other ids are not currently used.
dob	string	Date of birth in ISO 8601 date format.
gender	string	The user’s gender. Can be male, female or other.

Examples

Get the User Details for User 5769

curl -i 'https://store.shift72.com/services/users/users/5769/show' \
  -H 'x-auth-token: f217af8c0dc9dd4f257d2aef7ba8a962'

Response: Success

HttpStatus: 200
{  
  "id":5769,
  "name":"New Joe",
  "email":"user@example.com",
  "dob":"1999-01-30",
  "gender_id":"female",
  "status":"active",
  "last_sign_in":"2015-05-26T03:54:30.954Z",
  "sign_in_count":3,
  "roles_ids":[  
    1,
    2
  ]
}

Response: Unauthorized

HttpStatus: 401

Details Update

Summary: Update the user's details

Authentication: X-Auth

                      PUT /services/users/detail/update

Description

Use this API to update the user details of the currently signed in user.

Request Parameters

Parameter	Type	Description
name	string	Optional. The user’s new name.
email	string	Optional. The user’s new email address.
password	string	Optional. The user’s new password.
current_password	string	Required. The user’s current password.
dob	string	Optional. Date of birth in ISO 8601 date format.
gender	string	Optional. The user’s gender. Can be male, female or other.

Response Parameters

Parameter	Type	Description
success	string	A message that provides more information about the update.
error	string	A message that provides more information about the error.
field	string	The field that’s related to the error.

Examples

Update User’s Name

curl -i 'https://store.shift72.com/services/users/detail/update' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -H 'x-auth-token: 296871b9d469e9a2a3872c90a49d9212' \
     -d '{ "user": {
             "name": "New Joe",
             "current_password": "passw0rd"
             }
         }' \
     -X PUT

Update User’s Email Address

curl -i 'https://store.shift72.com/services/users/detail/update' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -H 'x-auth-token: 296871b9d469e9a2a3872c90a49d9212' \
     -d '{ "user": {
             "email": "joe@blogs.com",
             "current_password": "passw0rd"
             }
         }' \
     -X PUT

Update User’s Password

curl -i 'https://store.shift72.com/services/users/detail/update' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -H 'x-auth-token: 296871b9d469e9a2a3872c90a49d9212' \
     -d '{ "user": {
             "password": "passw0rd2",
             "current_password": "passw0rd"
             }
         }' \
     -X PUT

Response: Success

HttpStatus: 200
{  
  "success":"User has been updated"
}

Response: Failure

HttpStatus: 422
{  
  "error":"User failed to update incorrect password",
  "field":[  
    "current_password"
  ]
}

Response: Unauthorized

HttpStatus: 401

Details Update (Admin)

Summary: Update the user's details as an administrator

Authentication: X-Auth

                      PUT /services/users/users/[user_id]/update

Description

Use this API if you are an administrator and want to update the user details of a specific user. This API is only accessible to users who have the admin role.

Request Parameters

Parameter	Type	Description
id	number	The user’s unique ID.
name	string	Optional. The user’s name.
email	string	Optional. The user’s email address.
status	string	Optional. Either ‘suspended’, ‘blocklisted’, or ‘active’. Null and an empty string are the same as active.
last_sign_in	string	Deprecated. This will be removed in a future update.
sign_in_count	number	Deprecated. This will be removed in a future update.
owner_id	string	Deprecated. This will be removed in a future update.
encrypted_password	string	Deprecated. This will be removed in a future update.
roles_ids	number	Optional. An array of roles where 1 = admin. Other ids are not currently used.
dob	string	Optional. Date of birth in ISO 8601 date format.
gender	string	Optional. The user’s gender. Can be male, female or other.
notes	string	Optional. Notes to record for about the user.

Response Parameters

Returns User Details (Admin).

Examples

Update User’s Details

curl -i 'https://store.shift72.com/services/users/users/947/update' \
-X PUT \
-H 'content-type: application/json;charset=UTF-8' \
-H 'x-auth-token: 123197c039422f4e11c2caad08a50c3c' \
--data-binary '{ "user":{
    "id":947,
    "name":"New Joe",
    "email":"user@example.com",
    "gender":"female",
    "dob":"1999-01-30",
    "status":"active",
    "last_sign_in":"2015-07-20T01:01:11.740Z",
    "sign_in_count":3,
    "owner_id":null,
    "encrypted_password":"$2a$10$yn/1jIzmUBt0XS.cERDQFOo3RphdXcws01qBcTLM8Z.n8XWxjzXVC",
    "roles_ids":[] }
  }'

Response: Success

HttpStatus: 200
{
  "id":947,
  "name":"New Joe",
  "email":"user@example.com",
  "status":"active",
  "last_sign_in":"2015-07-20T01:01:11.740Z",
  "sign_in_count":2,
  "owner_id":null,
  "encrypted_password":"$2a$10$yn/1jIzmUBt0XS.cERDQFOo3RphdXcws01qBcTLM8Z.n8XWxjzXVC",
  "dob":"1999-01-30",
  "gender_id":"female",
  "client_id":2,
  "updated_at":"2015-07-20T01:38:33.573Z",
  "roles_ids":[]
}

Response: Unauthorized

HttpStatus: 401

Forgot Password

Summary: Request an email with password reset instructions

Authentication: None

                      POST /services/users/password/forgot

Description

Use this API to send an email with password reset instructions to the requested email address. If the user exists in the database they will be sent an email with reset instructions. If the user does not exist in the database then no email will be sent, even if the HTTP response was a 200. This is to prevent this API being abused.

Request Parameters

Parameter	Type	Description
email	string	Required. Email address of the user.

Response Parameters

Parameter	Type	Description
message	string	A message that provides more information about the response.

Examples

Forgot Password Request

curl https://store.shift72.com/services/users/password/forgot \
     -d 'user[email]=user@example.com' \
     -X POST

Response: Success

HttpStatus: 200
{  
  "message":"An email has been sent with a password reset link"
}

Reset Password

Summary: Reset a user's password

Authentication: X-Auth

                      PUT /services/users/password/reset

Description

Use this API to reset a user’s password. The id and reset_password_token are included in the link in the forgot password email that was requested in the Forgot Password API.

Request Parameters

Parameter	Type	Description
id	number	Required. The user’s account number.
reset_password_token	string	Required. The one-time use token required to reset the password for a specific user.
password	string	Required. User’s new password.
password_confirmation	string	Required. Must match the password.

Response Parameters

Returns user details.

Examples

Reset Password for User 659

curl -i 'https://store.shift72.com/services/users/password/reset' \
  -X PUT \
  -H 'content-type: application/json;charset=UTF-8' \
  -d '{ "user":{  
        "password":"password",
        "password_confirmation":"password",
        "id":"659",
        "reset_password_token":"ceb4d099d48445aa464b1d828e1fb1e5" }
      }'

Response: Success

HttpStatus: 200
{  
  "auth_token":"3018b0b31aecbc852fab31aec11e36c4",
  "account":{  
    "user_id":905,
    "email":"joe@example.com",
    "name":"Joe",
    "users":[  
      {  
        "id":905,
        "email":"joe@example.com",
        "name":"Joe",
        "avatar_url":null,
        "access_code":null,
        "account_admin":true,
        "dob":null
      }
    ],
    "bypass_cache":false
  }
}

Response: Failure - Invalid Token

HttpStatus: 422
{  
  "error":"Reset password token is invalid"
}

Response: Failure - Passwords Don’t Match

HttpStatus: 422
{  
  "error":"Password confirmation does not match password"
}

Response: Failure - Password Required

HttpStatus: 422
{
    "code": "password_required",
    "error": "Password required"
}

PIN Code Poll

Summary: Poll to Get User Details

Authentication: None

                      GET /services/users/v1/pin_codes/[id]

Description

Poll this API to get the user details once the user has confirmed the PIN Code.

Query String Request Parameters

Parameter	Type	Description
id	string	The UUID returned in the PIN Codes request.

Response Parameters

Returns User Details.

Examples

API Key Request

curl -i 'https://store.shift72.com/services/users/v1/pin_codes/4706c20a-3548-43b8-9058-3bdfcb3c9e8f'

Response: Success

HttpStatus: 200
{
  "auth_token": "e5273d36c3fc78c8c22be67cc3fbeed6",
  "account": {
    "user_id": 285,
    "email": "user@example.com",
    "name": "Example User",
    "dob": "1912-12-11",
    "gender": "male",
    "users": [
      {
        "id": 285,
        "email": "user@example.com",
        "name": "Example User",
        "avatar_url": null,
        "access_code": null,
        "account_admin": true,
        "dob": "1912-12-11",
        "gender": "male"
      }
    ],
    "bypass_cache": true,
    "permissions": {
      "show_all": true,
      "resources": {
        "/": [
          [
            "*"
          ]
        ]
      }
    }
  }
}

Response: Waiting for User to Register PIN Code

HttpStatus: 204

Response: Not Found

HttpStatus: 404
{
  "error":"Pin not found",
  "code":"pin_not_found"
}

PIN Code Request

Summary: Request a new PIN Code

Authentication: None

                      POST /services/users/v1/pin_codes

Description

Use this API to get a new PIN Code. This is used to make signing in from a device easier. The PIN code that is returned is to be displayed on the device and the user can then enter the PIN code on the website to confirm the sign in.

Request Parameters

Parameter	Type	Description
name	string	Required. User friendly name of the device.

Response Parameters

Parameter	Type	Description
code	string	PIN Code. The code the user enters.
id	string	UUID used to uniquely identify this request.
expiry	string	Expiry in ISO 8601 date format.

Examples

Request New PIN Code

curl -i 'https://store.shift72.com/services/users/v1/pin_codes' \
  -X POST \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "name":"Apple TV"
  }'

Response: Success

{“code”:”EO4N7”,”id”:”0fd03d2b-b231-4fa7-a73c-af415ce26296”,”expiry”:”2017-10-30T01:17:25.091Z”}

HttpStatus: 200
{  
  "code":"EO4N7",
  "id":"0fd03d2b-b231-4fa7-a73c-af415ce26296",
  "expiry":"2017-10-30T01:17:25.091Z"
}

Response: Missing Field

HttpStatus: 400
{  
  "error":"Name can not be blank",
  "code":"invalid_name"
}

PIN Code Register

Summary: Register a PIN Code

Authentication: X-Auth

                      POST /services/users/v1/pin_codes/register

Description

Use this API to register a PIN Code. This is entered by a user to activate a PIN Code displayed on a user’s device. This API is only accessible to users that are signed in.

Request Parameters

Parameter	Type	Description
code	string	Required. The code returned in the PIN Codes request.

Response Parameters

Parameter	Type	Description
name	string	User friendly name of the device.

Examples

Register PIN Code

curl -i 'https://store.shift72.com/services/users/v1/pin_codes/register' \
  -X POST \
  -H 'x-auth-token: a7499b7029d80791ff18834fec73aeee' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "code":"EMT0G"
  }'

Response: Success

HttpStatus: 200
{  
  "name":"Apple TV"
}

Response: Unauthorized

HttpStatus: 401

Response: Invalid PIN Code

HttpStatus: 404
{  
  "error":"Pin not found",
  "code":"pin_not_found"
}

Search

Summary: Search for users

Authentication: X-Auth Admin

                      GET /services/users/v2/users/search?page=[pg]&per_page=[num]&query=[search_string]&role_ids=[id]

Description

Use this API if you are an administrator and want to search the list of users. This searches across the name and email fields. This API is only accessible to users who have the admin role.

Query String Request Parameters

Parameter	Description
page	The search page number.
per_page	The number of items to return per page. All results are returned if this is not passed.
query	The string to search on.
role_ids	The role ids, where 1 = admin

Pagination Header Response Parameters

Pagination information is returned via the header Pagination

Parameter	Type	Description
page_size	number	The number of items per page.
first_page	number	The number of the first page.
next_page	number	The number of the next page.
prev_page	number	The number of the previous page.
last_page	number	The number of the last page.
total_count	number	The total number of items found in the search.
pages_count	number	The total number of pages.

Response Parameters

An array of the following items is returned.

Parameter	Type	Description
id	number	The user’s unique ID.
name	string	The user’s name.
email	string	The user’s email address.
status	string	Either ‘suspended’ or ‘active’. Null is the same as active.
last_sign_in	string	ISO 8601 format of the date and time the user last signed in.
sign_in_count	number	The number of times the user has signed in.
dob	string	Date of birth in ISO 8601 date format.
gender	string	The user’s gender. Can be male, female or other.

Examples

Search for Matches on “example”

curl -i 'https://store.shift72.com/services/users/v2/users/search?page=&per_page=20&query=example&role_ids=' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

[  
  {  
    "id":5769,
    "name":"New Joe",
    "email":"user@example.com",
    "status":"active",
    "last_sign_in":"2015-05-26T03:54:30.954Z",
    "sign_in_count":100,
    "dob": null,
    "gender": null
  },
  {  
    "id":5768,
    "name":"Test",
    "email":"me@example.com",
    "status":null,
    "last_sign_in":"2015-04-15T03:50:12.529Z",
    "sign_in_count":1,
    "dob": null,
    "gender": null    
  }
]

Response: Unauthorized

HttpStatus: 401

Search (CSV)

Summary: Search for users with the result as comma separated values

Authentication: X-Auth Admin

                      GET /services/users/v2/users/csv?auth_token=[auth_token]&query=[search_string]&role_ids=[id]

Description

Use this API if you are an administrator and want to search the list of users and get the result as comma separated values (CSV). This API is only accessible to users who have the admin role. This searches across the name and email fields.

Query String Request Parameters

Parameter	Description
auth_token	The user’s authorization token.
query	The string to search on.
role_ids	The role ids, where 1 = admin

Response Parameters

A CSV list of the following items is returned.

Parameter	Type	Description
Email	string	The user’s email address.
Name	string	The user’s name.
Created at	string	Date the user registered in ISO 8601 date format.
Gender	string	The user’s gender. Can be male, female or other.
DOB	string	Date of birth in ISO 8601 date format.
Sign In Attempts	number	The number of times the user has signed in.
Last Signed In	string	ISO 8601 format of the date and time the user last signed in.
Email Opt In	string	Either ‘TRUE’ or ‘FALSE’. Specifies if the user opted in to email marketing when creating an account.
ID	number	The user’s unique ID.
External ID	string	An external id for a user, often used to link to external auth providers.

Examples

Search for Matches on “example” with Result as CSV

curl -i  'https://store.shift72.com/services/users/v2/users/csv?&query=example&role_ids=' \
  -H 'x-auth-token: 267a4d0f684d39309252bf8eb3396a83'

Response: Success

HttpStatus: 200
"Email","Name","Created","Gender","DOB","Sign In Attempts","Last Signed In","Email Opt In","ID","External ID"
"user@example.com","Joe","2015-04-15","male","1901-12-25","448","2020-09-05T19:20:43Z","false","1",""
"me@example.com","Test","2015-04-15","","","2","2019-09-05T19:20:43Z","false","2","ABC123"

Response: Unauthorized

HttpStatus: 401

Exists

Summary: Confirm whether a user has a PIN code set or not

Authentication: X-Auth

                      GET /services/users/v1/user_pin_codes/exists

Description

Confirm whether the submitted user has a (non-blank, non-empty) PIN code set

Response Parameters

Returns a boolean indicating whether it is set

Examples

API Key Request

curl -i 'https://store.shift72.com/services/users/v1/user_pin_codes/exists'
	-H 'x-auth-token: 296871b9d469e9a2a3872c90a49d9212' \
	 -X GET

Response: PIN is set

HttpStatus: 200 { "result": true }

Response: PIN is not set

HttpStatus: 200 { "result": false }

Update

Summary: Update a user's PIN code

Authentication: X-Auth

                      PUT /services/users/v1/user_pin_codes/update

Description

Set a user’s PIN code, provided it passes validation

Request Parameters

Parameter	Type	Description
pin	string	PIN submitted by user
password	string	Password submitted by user

Response Parameters

Returns a response code and error object (where applicable)

Examples

API Key Request

curl -i 'https://store.shift72.com/services/users/v1/user_pin_codes/verify'
  -H 'x-auth-token: 296871b9d469e9a2a3872c90a49d9212' \
   -d '{ "pin": 1234, "password": "p4ssw0rd" }' \
   -X POST

Response: Success

HttpStatus: 200 { "success": "Pin has been updated" }

Response: Missing ‘pin’ parameter

HttpStatus: 422
{
  "error": "Pin required",
  "code": "missing_pin"
}

Response: Missing ‘password’ parameter

HttpStatus: 422
{
  "error": "Password required",
  "code": "missing_password"
}

Response: Wrong password

HttpStatus: 422
{
  "error": "Wrong password",
  "code": "wrong_password"
}

Response: PIN contains non-numeric characters

HttpStatus: 422
{
  "error": "Pin should comprise only digits",
  "code": "pin_includes_non_numeric"
}

Response: PIN is too long

By default, PIN codes are 4 digits long, but this can be reconfigured.

HttpStatus: 422
{
  "error": "Pin too long",
  "code": "pin_too_long"
}

Response: PIN is too short

HttpStatus: 422
{
  "error": "Pin too short",
  "code": "pin_too_short"
}

Verify

Summary: Verify a user's PIN code

Authentication: X-Auth

                      POST /services/users/v1/user_pin_codes/verify

Description

Verify a user’s PIN code before allowing them to purchase/rent/play restricted content

Query String Request Parameters

Parameter	Type	Description
pin	string	PIN submitted by user

Response Parameters

Returns a response code and error object (where applicable)

Examples

API Key Request

curl -i 'https://store.shift72.com/services/users/v1/user_pin_codes/verify'
  -H 'x-auth-token: 296871b9d469e9a2a3872c90a49d9212' \
   -d '{ "pin": 1234 }' \
   -X POST

Response: Success

HttpStatus: 200 {}

Response: Missing ‘pin’ parameter

HttpStatus: 422
{
  "error": "Pin required",
  "code": "missing_pin"
}

Response: User PIN isn’t set

HttpStatus: 403
{
  "error": "User PIN not set",
  "code": "user_pin_not_set"
}

Response: User not Found

HttpStatus: 404
{
  "error": "User not found",
  "code": "user_not_found"
}

Response: Wrong PIN

HttpStatus: 403
{
  "error": "Wrong PIN",
  "code": "wrong_pin"
}

Wishlists

Summary: Get a user's wishlist items

Authentication: X-Auth

                      GET /services/users/v1/wishlist

Description

Return a list of content slugs which the user has added to their wishlist. The supported slugs are films, TV Shows and TV Seasons.

Examples

Retrieve the List of Items in the Wishlist

curl -i 'https://store.shift72.com/services/users/v1/wishlist' \
  -H 'x-auth-token: 980d099188d97f8e213ec9d6a4660b78'

Response: Success

Returns the up-to-date wishlist, most-recently added records first.

HttpStatus: 200
{
   [ "/film/32", "/tv/64", "/tv/128/season/1" ]
}

Response: Unauthorized

HttpStatus: 401

Adding items to a wishlist

Summary: Add a content item to a user's wishlist

Authentication: X-Auth

                      POST /services/users/v1/wishlist[slug]

Description

Add the submitted content to the logged-in user’s wishlist. The supported slugs are films, TV Shows and TV Seasons.

Examples

Add Content to the Wishlist

curl -i 'https://store.shift72.com/services/users/v1/wishlist/film/49' \
  -X POST \
  -H 'x-auth-token: 980d099188d97f8e213ec9d6a4660b78'

Response: Success

Returns the up-to-date wishlist, most-recently added records first.

HttpStatus: 200
{
   [ "/film/49", "/film/32", "/tv/64", "/tv/128/season/1" ]
}

Response: Unauthorized

HttpStatus: 401

Removing items from a wishlist

Summary: Remove a content item from a user's wishlist

Authentication: X-Auth

                      DELETE /services/users/v1/wishlist[slug]

Description

Remove the submitted content from the logged-in user’s wishlist. The supported slugs are films, TV Shows and TV Seasons.

Examples

Remove Item from the Wishlist

curl -i 'https://store.shift72.com/services/users/v1/wishlist/film/49' \
  -X DELETE \
  -H 'x-auth-token: 980d099188d97f8e213ec9d6a4660b78'

Response: Success

Returns the up-to-date wishlist, most-recently added records first, without the submitted slug.

HttpStatus: 200
{
   [ "/film/32", "/tv/64", "/tv/128/season/1" ]
}

Response: Unauthorized

HttpStatus: 401

Analytics

Summary: Record an analytic event

Authentication: None, X-Auth

                  POST /services/users/v1/analytics

Description

Use this API to record analytics events. You can optionally provide a slug if the event relates to specific content. Analytics are anonymous by default, but an x-auth-token header can be provided to associate it with a specific user.

Request Parameters

Parameter	Type	Description
event_name	string	Required. Name of analytics event.
timestamp	string	Required. Analytic timestamp in ISO 8601 UTC time format.
slug	string	Optional. The slug of the content that the analytic event relates to.

Response Parameters

Parameter	Type	Description
success	bool	Set to true if analytic successfully saved.

Examples

Trailer Play Button Clicked

curl -i 'https://store.shift72.com/services/users/v1/analytics' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{
    "event_name":"trailer_play_button_clicked",
    "timestamp":"2020-01-01T00:00:00.000Z",
    "slug":"/film/200"
  }'

Response: Success

HttpStatus: 200
{
  "success":true
}

Response: Analytics Configuration Disabled

HttpStatus: 403
{
  "error":"analytics_disabled",
  "code":"analytics_disabled"
}

Response: Invalid Event Name

HttpStatus: 422
{
  "error":"event name must be a string",
  "code":"invalid_event_name"
}

Response: Invalid Timestamp

HttpStatus: 422
{
  "error":"timestamp must be a valid timestamp string",
  "code":"invalid_timestamp"
}

Response: Analytic Insertion Failed

HttpStatus: 422
{
  "code":"analytic_insertion_failed"
}

Branding

Summary: Get the branding information

Authentication: None

                  GET /services/users/v1/branding

Description

This API is used to receive information about the client’s brand.

Response Parameters

Parameter	Type	Description
domain	string	The domain used for API calls.
support_address	string	Email address to display for support queries.
name	string	The name of the client.
brandings[brand-color]	string	Primary brand colour.
brandings[brand-color-secondary]	string	Secondary brand colour.
brandings[text-color]	string	Primary text colour.
brandings[text-color-secondary]	string	Secondary text colour.
brandings[logo-url]	string	Link to the location of the client’s logo.

Examples

Request Client Information

curl -i 'https://store.shift72.com/services/users/v1/branding'

Response: Success

HttpStatus: 200
{  
   "name":"s72demo",
   "domain":"store.shift72.com",
   "support_address":"vod@shift72.com",
   "brandings":{  
      "brand-color":"#0b54a9",
      "brand-color-secondary":"#0e6cd9",
      "text-color":"#ffffff",
      "text-color-secondary":"#ffffff",
      "logo-url":"https://store.shift72.com/images/common/app-logo.png"
   }
}

Clients

Summary: Get the list of clients that are to appear in the SHIFT72 or ScreenPlus apps

Authentication: None

                  GET /services/users/v1/clients

Description

This API is used to receive information about the clients that are used in the SHIFT72 or ScreenPlus apps. This includes information about the client including brand colours. This API allows new clients to be added to the SHIFT72 and ScreenPlus apps without having to release a new version of the app.

Request Parameters

Parameter	Type	Description
org	string	Optional. If this is set to `screenplus`, only clients marked as ScreenPlus clients will be returned.

Response Parameters

Parameter	Type	Description
id	number	The ID of the client.
domain	string	The domain used for API calls.
description	string	Short description about the client.
rank	number	The rank of the client, i.e. the order to appear within the app.
name	string	The name of the client.
branding[brand-color]	string	Primary brand colour.
branding[brand-color-secondary]	string	Secondary brand colour.
branding[text-color]	string	Primary text colour.
branding[text-color-secondary]	string	Secondary text colour.
branding[logo-url]	string	Link to the location of the client’s logo.
links[about-us]	string	Optional. Overwrite the default link to the client’s About Us page.
links[help]	string	Optional. Overwrite the default link to the client’s Help page.
links[terms-and-conditions]	string	Optional. Overwrite the default ink to the client’s Terms and Conditions page.
links[forgot-password]	string	Optional. Overwrite the default link to the client’s Forgot Password page.
links[privacy-policy]	string	Optional. Overwrite the default link to the client’s Privacy Policy page.

Examples

Request SHIFT72 App Information

curl -i 'https://api.shift72.com/services/users/v1/clients'

Response: Success

HttpStatus: 200
[
  {
    "id":3,
    "domain":"ondemand.nzfilm.co.nz",
    "description":"NZ Film On Demand is the New Zealand Film Commission's On Demand service which brings great New Zealand films to you when you want.",
    "rank":1,
    "name":"NZ Film",
    "branding":{
      "brand-color":"#000000",
      "brand-color-secondary":"#39A8A3",
      "text-color":"#ffffff",
      "text-color-secondary":"#ffffff",
      "logo-url":"https://ondemand.nzfilm.co.nz/images/common/app-logo.png"
    },
    "links":null
  },
  {
    "id":10,
    "domain":"buymovie.whatwedointheshadows.com",
    "description":"Follow the lives of Viago (Taika Waititi), Deacon (Jonathan Brugh), and Vladislav (Jemaine Clement) - three flatmates who are just trying to get by and overcome life's obstacles-like being immortal vampires who must feast on human blood.",
    "rank":2,
    "name":"What We Do in the Shadows",
    "branding":{
      "brand-color":"#000000",
      "brand-color-secondary":"#000000",
      "text-color":"#ffedbc",
      "text-color-secondary":"#ffedbc",
      "logo-url":"https://buymovie.whatwedointheshadows.com/images/common/app-logo.png"
    },
    "links":null
  },
  {
    "id":2,
    "domain":"store.shift72.com",
    "description":"A demo site showcasing the latest features from SHIFT72.",
    "rank":3,
    "name":"SHIFT72 Demo",
    "branding":{
      "brand-color-secondary":"#0e6cd9",
      "text-color":"#ffffff",
      "text-color-secondary":"#eeeeee",
      "brand-color":"#0b54a9",
      "logo-url":"https://store.shift72.com/images/common/app-logo.png"
    },
    "links":{
      "about-us":"https://store.shift72.com/#!/page/about-us",
      "help":"https://store.shift72.com/#!/page/help",
      "terms-and-conditions":"https://store.shift72.com/#!/page/terms-and-conditions",
      "forgot-password":"https://store.shift72.com/#!/forgot-password",
      "privacy-policy":"https://store.shift72.com/#!/page/privacy"
    }
  }
]

Request ScreenPlus App Information

curl -i 'https://api.shift72.com/services/users/v1/clients?org=screenplus'

Response: Success

HttpStatus: 200
[
  {
    "id":2,
    "domain":"store.shift72.com",
    "description":"A demo site showcasing the latest features from SHIFT72.",
    "rank":3,
    "name":"SHIFT72 Demo",
    "branding":{
      "brand-color-secondary":"#0e6cd9",
      "text-color":"#ffffff",
      "text-color-secondary":"#eeeeee",
      "brand-color":"#0b54a9",
      "logo-url":"https://store.shift72.com/images/common/app-logo.png"
    },
    "links":{
      "about-us":"https://store.shift72.com/#!/page/about-us",
      "help":"https://store.shift72.com/#!/page/help",
      "terms-and-conditions":"https://store.shift72.com/#!/page/terms-and-conditions",
      "forgot-password":"https://store.shift72.com/#!/forgot-password",
      "privacy-policy":"https://store.shift72.com/#!/page/privacy"
    }
  }
]

Create User

Summary: Create a new user

Authentication: X-Auth Admin

                  POST /services/users/users

Description

Use this API to create a new user with the supplied details. On successful creation the new user will not be sent a welcome email. This API is useful for migration or 3rd party authentication integrations. A random password is created during this process. This API is only accessible to users who have the admin role.

Request Parameters

Parameter	Type	Description
name	string	Required. Name of the user.
email	string	Required. Email address of the user.
dob	string	Optional. Date of birth in ISO 8601 date format.
gender	string	Optional. The user’s gender. Can be male, female, diverse, other, or not specified (null).
external_id	string	Optional. An external id for a user, used to link to external auth providers.

Response Parameters

Returns user details (admin).

Examples

Create User Request

curl -i 'https://store.shift72.com/services/users/users' \
  -X POST \
  -H 'x-auth-token: f217af8c0dc9dd4f257d2aef7ba8a962' \
  -H 'content-type: application/json;charset=UTF-8' \
  -d '{ "user":{  
          "name":"Joe",
          "email":"user@example.com",
          "dob":"2000-01-31",
          "gender":"male"
        }
      }'

Response: Success

HttpStatus: 200
{  
  "id":5769,
  "name":"Joe",
  "email":"user@example.com",
  "dob":"2000-01-31",
  "gender_id":"male",
  "status":"active",
  "last_sign_in":null,
  "sign_in_count":0,
  "roles_ids":[]
}

Response: Failure

HttpStatus: 422
{  
  "error":{  
    "email":[  
      "email address has already been taken"
    ]
  }
}

Response: Unauthorized

HttpStatus: 401

Delete User

Summary: Delete a user account

Authentication: X-Auth Admin

                  DELETE /services/users/v2/users/[id]

Description

Use this API to delete the user account with the given ID. This API is only accessible to users who have the admin role.

Examples

Delete Request

curl -i https://store.shift72.com/service/users/v2/users/1 \
  -X DELETE \
  -H 'x-auth-token: f217af8c0dc9dd4f257d2aef7ba8a962'  

Response: Success

HttpStatus: 200

Response: User Not Found

HttpStatus: 404
{
  "error":"User could not be found",
  "code":"user_not_found"
}

Response: User Not Deleted

HttpStatus: 422
{
  "error":"error occured during anonymization",
  "code":"user_not_deleted"
}

Feature Toggles

Summary: Request user feature toggle settings

Authentication: None

                  GET /services/users/v1/feature_toggles

Description

Use this API to get the feature toggle settings for the User service. The feature toggles are used to control if clients have access to features that are in beta. The feature toggles are not listed here as they are usually short lived and are only required for controlling access to features that are in beta testing.

Examples

User Feature Toggles Request

curl -i 'https://store.shift72.com/services/users/v1/feature_toggles'

Response: Success

HttpStatus: 200
{  
  "user_invite":true,
  "user_activity":false
}

Invite Users

Summary: Invite a user

Authentication: X-Auth Admin

                  POST /services/users/v1/invite

Description

Use this API to create a user account and send an email with instructions on how to register their account. You can optionally subscribe a user to a plan or add films or seasons to their library. For existing admin users with a role defined, setting reinvite to false will send a reminder email, setting reinvite to true will reset their password and send the invite email again. For normal users, setting reinvite to false will update their settings but not send an email, setting reinvite to true will reset their password and send the invite email again.

Request Parameters

Parameter	Type	Description
invitees	array	Required. Array of email addresses to invite.
items	array	Optional. Array of items to be added to the users’ libraries. These can be films, seasons, or plans.
expiry	string	Optional. Rental expiry in ISO 8601 UTC time format.
reinvite	bool	Optional. Set to true if you want to reset the password and send the invite email again.
role	string	Optional. The admin role to give to the new user.
resource	array	Optional. Array of resources to apply to the role. These can be films or seasons.

Response Parameters

Parameter	Type	Description
invites_sent	number	The number of new users created.
existing_users_invited	number	The number of existing users. These will only be sent if reinvite was set to true.

Examples

Invite User with Rental

curl -i 'https://store.shift72.com/services/users/v1/invite' \
  -H 'x-auth-token: 123197c039422f4e11c2caad08a50c3c' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "invitees":[  
      "user@example.com"
    ],
    "items":[  
      "/film/64"
    ],
    "reinvite":true,
    "expiry":"2017-06-15T23:10:09.824Z"
  }'

Invite User with Distributor Role

curl -i 'https://store.shift72.com/services/users/v1/invite' \
  -H 'x-auth-token: 123197c039422f4e11c2caad08a50c3c' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "invitees":[  
      "user@example.com"
    ],
    "reinvite":true,
    "role":"Distributor",
    "resource":[  
      "/film/333"
    ]
  }'

Response: Success

HttpStatus: 200
{  
  "invites_sent":1,
  "existing_users_invited":0
}

Response: Unauthorized

HttpStatus: 401

Response: Missing Email Addresses

HttpStatus: 400
{  
  "error":"Missing invitees"
}

Response: Invalid Email Addresses

HttpStatus: 400
{  
  "error":"Contains invalid emails addresses"
}

Response: Role Doesn’t Exist

HttpStatus: 400
{  
  "error":"Role doesn't exist"
}

Resources

Summary: Get a list of users who are assigned to this resource

Authentication: X-Auth Admin

                  GET /services/users/users/resource_users/[slug]

Description

Return a list of users who have been assigned a role to the specified resource. This API is only accessible to users who have the admin role.

Response Parameters

Returns User Details (Admin).

Examples

Retrieve List of Users for Film 71

curl -i 'https://store.shift72.com/services/users/users/resource_users/film/71' \
  -H 'x-auth-token: 980d099188d97f8e213ec9d6a4660b78'

Response: Success

HttpStatus: 200
[
  {  
    "id":5769,
    "name":"New Joe",
    "email":"user@example.com",
    "dob":"1999-01-30",
    "gender_id":"female",
    "status":"active",
    "last_sign_in":"2015-05-26T03:54:30.954Z",
    "sign_in_count":3,
    "roles_ids":[  
      3
    ]
  }
]

Response: Unauthorized

HttpStatus: 401

User Service

Description

Response Parameters

Examples

API Key Request

Response: Success

Response: Not Found

Response: Unauthorized

Description

Response Parameters

Examples

Request New API Key

Response: Success

Response: Unauthorized

Description

Response Parameters

Examples

Check If User Is an Administrator

Response: Success

Response: Unauthorized

Description

Request Parameters

Response Parameters

Examples

Sign In Request

Sign In Request With Optional Field

Response: Success

Response: Failure

Description

Response Parameters

Examples

Sign Out Request

Response: Success

Description

Request Parameters

Response Parameters

Examples

Sign Up Request

Response: Success

Response: Failure

Description

Query String Request Parameters

Response Parameters

Examples

Check if Email Exists

Check if Account exists using an external id

Response: Success

Response: Missing Email

Description

Response Parameters

Examples

Users Configuration Request

Response: Success

Description

Response Parameters

Examples

Admin Configuration Request

Response: Success

Response: Unauthorized

Description

Request Parameters

Response Parameters

Examples

Update Field

Response: Success

Response: Key Doesn’t Exist

Response: Unauthorized

Description

Response Parameters

Examples

User Details Request

Response: Success

Response: Unauthorized

Description

Response Parameters

Examples

Get the User Details for User 5769

Response: Success

Response: Unauthorized

Description