User Service

The user service is responsible for managing user registrations.

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
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
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
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

Sign In Request

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"
            }
        }'

Sign In Request With Optional Field

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"
}
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
}
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

Sign Up Request

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"
    ]
  }
}

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"
}
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"
}
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
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
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
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
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
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
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"
}
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"
}

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"
}
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"
}
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"
}
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
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
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 }
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"
}
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"
}
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
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
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
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"
}
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"
   }
}
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"
    }
  }
]
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
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"
}
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
}
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"
}
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