Introduction

👏 Welcome to the Reward Gateway Developer Portal 👏

The Reward Gateway Developer Portal provides a single source of truth for all developers to locate, access and consume services within Reward Gateway.

Authentication

All Reward Gateway APIs implement OAuth 2.0 to allow users to log in to applications without exposing their credentials. The process involves several steps:

Acquire an access token, and a refresh token
Use the access token to make authenticated requests
If you were issued a refresh token: refresh the access token when it expires

Before you begin, you will need to create a client. You can do this by accessing the Integration Dashboard on Reward Manager and selecting the REST API option.

Obtaining an access token

Obtaining an access token is a three-step process (3-legged oAuth):

Redirect the user to Reward Gateway Identity to authorise your app
Reward Gateway Identity redirects the user back to your app with an authorization code
Exchange the authorization code for an access token.

Redirect the user to Reward Gateway Identity

Send the user to Reward Gateway Identity in a web browser, where they will log in and grant access to their account.

Parameter	Required	Description
`client_id`	true	Your client ID.
`redirect_uri`	true	A URI to which users will be redirected after authorising your app.
`response_type`	true	Must be set to `code`
`state`	false	An unguessable random string used to protect against cross-site request forgery attacks.

Reward Gateway Identity redirects the user

https://identity.rewardgateway.net/?
    client_id=$client_id&
    redirect_uri=$redirect_uri&
    response_type=code&
    state=$state_token

https://example.com/oauth/callback?
    code=$authorization_code&
    state=$state_token

If the user allows access to their account, Reward Gateway Identity redirects them back to your app.

Parameter	Description
`code`	A temporary authorization code which will be exchanged for an access token in the next step.
`state`	The same string you provided as state when sending the user to Reward Gateway Identity. If this value differs from what you sent, you must abort the authentication process.

Exchange the authorization code

http --form POST "https://identity.rewardgateway.net/access_token" \
    "grant_type=authorization_code" \
    "client_id=$client_id" \
    "client_secret=$client_secret" \
    "redirect_uri=$redirect_uri" \
    "code=$authorization_code"

{
    "access_token": "access_token",
    "refresh_token": "refresh_token",
    "token_type": "Bearer",
    "expires_in": 3600
}

When you receive an authorization code, exchange it for an access token. The resulting access token is tied to both your client and an individual Reward Gateway user, and is valid for 1 hour.

Parameter	Required	Description
`grant_type`	true	This must be set to `authorization_code`
`client_id`	true	Your client ID.
`client_secret`	true	Your client secret.
`redirect_uri`	true	The URL in your app where users were sent after authorisation.
`code`	true	The authorization code you received when the user was redirected back to your app.

Authenticating requests

http "https://api.rewardgateway.net/user/me" \
    "Authorization: Bearer $access_token"

All requests must be authenticated with an access token supplied in the Authorization header using the Bearer scheme. Your client may only have one active access token at a time, per user. Acquiring a new access token will invalidate any other token you own for that user.

To get information about an access token, you can call the /user/me endpoint.

Refreshing access

http --form POST "https://identity.rewardgateway.net/access_token" \
    "grant_type=refresh_token" \
    "client_id=$client_id" \
    "client_secret=$client_secret" \
    "refresh_token=$refresh_token"

{
    "access_token": "access_token",
    "refresh_token": "refresh_token",
    "token_type": "Bearer",
    "expires_in": 3600
}

Each access token expires after 1 hour. To gain long-lived access to a user’s account, it’s necessary to “refresh” your access when it expires using a refresh token.

Refreshing an access token will invalidate the previous token, if it is still valid. Refreshing is a one-time operation.

Parameter	Required	Description
`grant_type`	true	This must be set to `refresh_token`
`client_id`	true	Your client ID.
`client_secret`	true	Your client secret.
`refresh_token`	true	The refresh token received along with the original access token.

Log Out

http --form POST "https://api.rewardgateway.net/auth/logout" \
    "Authorization: Bearer $access_token"

While access tokens do expire after one hour, you may wish to invalidate the token instantly at a specific time such as when a user chooses to log out of your application.

Once invalidated, the user must go through the authentication process again. You will not be able to refresh the access token.

REST API

The Reward Gateway REST API is designed to be a predictable and intuitive interface for interacting with all Reward Gateway products.

The base url for all REST API calls is: https://api.rewardgateway.net/

Endpoints

The REST API supports multiple versions which are listed below along side the relevant API Endpoints and documentation.

Version	Support	Documentation
`v1`	Deprecated	v1 API Documentation
`v2`	Recommended	v2 API Documentation
`v3`	Beta	v3 API Documentation

Versioning

http --form POST "https://api.rewardgateway.net/user/me" \
    "Authorization: Bearer $access_token" \
    "Accept: application/vnd.rewardgateway+json;version=2.0"

To access a specific version of the REST API, an Accept header MUST be passed. If no Accept header is passed Reward Gateway would automatically default to least supported version (Recommended version above).

SCIM API

What is SCIM?

SCIM stands for “System for Cross-domain Identity Management". It's a standardized way of representing users, groups, and anything else related. SCIM helps to standardize methods for acting on this data, such as creating, querying, searching, updating and deleting. In other words, it’s an API model.

These two parts of SCIM are split into two standards:

A Core Schema RFC7643 controlling how the data is modelled.
A Protocol for interacting with the data RFC7644. Learn More

What is SCIM used for?

SCIM is used by Single Sign-On (SSO) services and identity providers to manage people across a variety of tools, including Reward Gateway, and is an API for managing the employee data of clients. It provides an easy way for our clients to manage new hires and leavers from their business, ensuring they have the right access to the program at the right times – e.g. new hires will be added once joined and leavers will be removed once they leave. This will work automatically via the SCIM integration and will require no additional input from HR.

What SCIM versions are supported by Reward Gateway?

Reward Gateway currently supports SCIM version 1.1 and SCIM version 2.0.

Authentication

Reward Gateway SCIM API uses oAuth 2.0 for authenticating requests. However, this is slightly different to authenticating requests with the REST API as explained here.

As SCIM API is used to provision users across a specific tenant, a special delegated token which is scoped to do so must be used. To obtain one of these delegated tokens, please go into the Integration Dashboard on Reward Manager and choose SCIM API.

This will generate you the following:

A unique SCIM API Base URL
An access token for sending authenticated requests

The base url for all SCIM Requests follows this format: https://api.rewardgateway.net/{programme_guid}/scim/{version}/

Supported Methods

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users \
  -H 'Authorization: Bearer $delegated_token' \
  -H 'Accept: application/json'

All SCIM methods are accessed over the HTTP protocol. Being a REST API, the HTTP Verbs (e.g. GET, POST, PUT, PATCH and DELETE) used to access each method are extremely important.

GET – Retrieve Information about a User or Users.
POST – Create a new user.
PUT / PATCH – Modify a user.
DELETE – Remove a user.

You MUST provide a JSON request body for POST, PUT, and PATCH write operations.

Endpoints

Service Provider Configurations

GET /ServiceProviderConfigs

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/ServiceProviderConfigs \
  -H 'Accept: application/json'

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "patch": {
        "supported": true
    },
    "bulk": {
        "supported": false,
        "maxOperations": 0,
        "maxPayloadSize": 0
    },
    "filter": {
        "supported": true,
        "maxResults": 10
    },
    "changePassword": {
        "supported": true
    },
    "sort": {
        "supported": false
    },
    "etag": {
        "supported": false
    },
    "authenticationSchemes": [
        {
            "name": "OAuth Bearer Token",
            "description": "Authentication scheme using the OAuth Bearer Token Standard",
            "specUri": "http://www.rfc-editor.org/info/rfc6750",
            "type": "oauthbearertoken",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "ServiceProviderConfig",
        "location": "v2/ServiceProviderConfig"
    }
}

Returns Reward Gateway’s configuration details for the client platform SCIM API. This includes which operations are supported. Learn More

Schemas

GET /Schemas/User

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Schemas/User \
  -H 'Accept: application/json' \

{
    "id": "urn:ietf:params:scim:schemas:core:2.0:User",
    "name": "User",
    "description": "Core User",
    "schema": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "schemaExtensions": {
        "schema": "urn:ietf:params:scim:schemas:rewardgateway:2.0:User",
        "required": false
    },
    "endpoint": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Schemas/User",
    "attributes": {
        "id": {
            "name": "id",
            "type": "string",
            "description": "Unique attribute defined by the Service Provider",
            "multiValued": false,
            "required": true,
            "caseExact": false,
            "mutability": "readOnly",
            "returned": "always",
            "uniqueness": "server",
            "subAttributes": []
        },
        "externalId": {
            "name": "externalId",
            "type": "string",
            "description": "Unique identifier defined by the Identity Provider or SCIM provider (Will take precedence over userName)",
            "multiValued": false,
            "required": false,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "server",
            "subAttributes": []
        },
        "userName": {
            "name": "userName",
            "type": "string",
            "description": "A service provider's unique identifier for the user, typically used to directly authenticate to SCIM provider.",
            "multiValued": false,
            "required": true,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "server",
            "subAttributes": []
        },
        "name": {
            "name": "name",
            "type": "complex",
            "description": "Components of the users real name",
            "multiValued": false,
            "required": true,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": {
                "familyName": {
                    "name": "familyName",
                    "type": "string",
                    "description": "Family Name of the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "givenName": {
                    "name": "givenName",
                    "type": "string",
                    "description": "Given Name of the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                }
            }
        },
        "emails": {
            "name": "emails",
            "type": "complex",
            "description": "Components of the users email address",
            "multiValued": true,
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": {
                "value": {
                    "name": "value",
                    "type": "string",
                    "description": "Email address of the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "primary": {
                    "name": "primary",
                    "type": "boolean",
                    "description": "Indicate if the email address is the primary email for the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                }
            }
        },
        "locale": {
            "name": "locale",
            "type": "string",
            "description": "A string value indicating the User's locale. e.g. en-US, en-GB",
            "multiValued": false,
            "required": false,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        },
        "active": {
            "name": "active",
            "type": "boolean",
            "description": "A Boolean value indicating the User's status.",
            "multiValued": false,
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        },
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
            "name": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "type": "complex",
            "description": "The following SCIM extension defines attributes commonly used in representing users that belong to, or act on behalf of a business or enterprise.",
            "multiValued": false,
            "required": false,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": {
                "costCenter": {
                    "name": "costCenter",
                    "type": "string",
                    "description": "Identifies a Cost Center",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "organization": {
                    "name": "organization",
                    "type": "string",
                    "description": "Identifies an Organisation",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "division": {
                    "name": "division",
                    "type": "string",
                    "description": "Identifies a Division",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "department": {
                    "name": "department",
                    "type": "string",
                    "description": "Identifies a Department",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "manager": {
                    "name": "manager",
                    "type": "complex",
                    "description": "The User's manager. A complex type that optionally allows Service Providers to represent organizational hierarchy by referencing the \\\"id\\\" attribute of another User.",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": {
                        "managerId": {
                            "name": "managerId",
                            "type": "string",
                            "description": "The external id of the SCIM resource representing the User's manager.",
                            "multiValued": false,
                            "required": false,
                            "caseExact": true,
                            "mutability": "readWrite",
                            "returned": "always",
                            "uniqueness": "none",
                            "subAttributes": []
                        },
                        "value": {
                            "name": "value",
                            "type": "string",
                            "description": "The SCIM resource id of the SCIM resource representing the User's manager. ",
                            "multiValued": false,
                            "required": true,
                            "caseExact": false,
                            "mutability": "readWrite",
                            "returned": "always",
                            "uniqueness": "none",
                            "subAttributes": []
                        }
                    }
                }
            }
        },
        "roles": {
            "name": "roles",
            "type": "complex",
            "description": "List of user roles assigned to the member",
            "multiValued": false,
            "required": false,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        },
        "urn:ietf:params:scim:schemas:rewardgateway:2.0:User": {
            "name": "urn:ietf:params:scim:schemas:rewardgateway:2.0:User",
            "type": "complex",
            "description": "The following SCIM extension defines attributes that are custom to your organisation and are configured through Reward Manager.",
            "multiValued": false,
            "required": false,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        }
    },
    "meta": {
        "resourceType": "Schema",
        "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Schemas/User"
    }
}

Reward Gateway currently supports schemas for Users. Querying the schemas will provide the most up to date rendering of the supported SCIM attributes. We do not currently support schemas for Groups.

Users

Attributes are the information associated with a user's account. This is information that someone would typically set in their profile.

The following tables map SCIM attributes to the profile fields that Slack uses. Most of these profile fields are exposed directly in Reward Manager to be amended or in the My Account section of the programme where the member can edit it. Sometimes, multiple SCIM attributes map to a single profile field – for example, externalId field and userName field both map to a single unique identifier on Reward Gateway.

SCIM Attribute Mapping

Reward Gateway Field	SCIM Field	Description	Attribute Type	Required	Read Only
Member ID (UUID)	`id`	Unique Identifier associated to a user on Reward Gateway	Singular	True	True
Membership No (Payroll Number, Employee Number)	`userName`	Unique Identifier associated to a user on the Identity Provider	Singular	True	False
Membership No (Payroll Number, Employee Number)	`externalId`	Unique Identifier associated to a user on the Identity Provider	Singular	True	False
First Name	`name.givenName`	User’s First Name	Singular	True	False
Last Name	`name.familyName`	User’s Last Name	Singular	True	False
Email Address	`emails[0]['value']`	User’s Email Address associated with the account	Multi-Valued	True	False
Licence Country	`locale`	Locale¹ of the member	Singular	False	False
Eligibility Status	`active`	Eligibility status of the member. If passed as false will begin the account shut-down process.	Singular	False	False
Cost Center	`enterprise.costCenter`	Cost Center associated with the member	Singular	False	False
Organization	`enterprise.organization`	Organization associated with the member	Singular	False	False
Division	`enterprise.division`	Division associated with the member	Singular	False	False
Department	`enterprise.department`	Department associated with the member	Singular	False	False
Line Manager ID	`enterprise.manager.value`	Line Manager associated with the member	Multi-Valued	False	False

[1] The locale is specified in the format “en_[CountryCode]”, where CountryCode follows the two letter ISO 3166-1 standard (e.g. Italy is represented as the en_IT locale).

GET /Users

Returns a paginated list of users, ten users per page by default. To be able to paginate through the list of users please use the startIndex and count query parameters.

It's also possible to return a list of specific types of users through filtering. Learn more about filtering below.

Filters

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 2,
    "startIndex": 1,
    "itemsPerPage": 10,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "id": "8ab860d9-891f-4f8d-b454-9a012e001b92",
            "externalId": "",
            "userName": "",
            "name": {
                "familyName": "User",
                "givenName": "A"
            },
            "photos": [
                {
                    "value": "https://static.cdn.rewardgateway.net/BrandAssets/responsive/img/avatars/200x200_default-5.png",
                    "type": "photo"
                }
            ],
            "emails": [
                {
                    "value": "user.a@example.com",
                    "primary": true
                }
            ],
            "locale": "",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "costCenter": "",
                "organization": "",
                "division": "",
                "department": "",
                "manager": {
                    "managerId": "",
                    "value": ""
                }
            },
            "roles": [],
            "active": false,
            "meta": {
                "resourceType": "User",
                "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "id": "8ab86436-9035-4b79-99f4-061f768665c1",
            "externalId": "",
            "userName": "",
            "name": {
                "familyName": "User",
                "givenName": "B"
            },
            "photos": [
                {
                    "value": "https://static.cdn.rewardgateway.net/BrandAssets/responsive/img/avatars/200x200_default-5.png",
                    "type": "photo"
                }
            ],
            "emails": [
                {
                    "value": "user.b@example.com",
                    "primary": true
                }
            ],
            "locale": "",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "costCenter": "",
                "organization": "",
                "division": "",
                "department": "",
                "manager": {
                    "managerId": "",
                    "value": ""
                }
            },
            "roles": [],
            "active": false,
            "meta": {
                "resourceType": "User",
                "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Users/8ab86436-9035-4b79-99f4-061f768665c1"
            }
        }
    ]
}

It's possible to filter the list of users returned through the SCIM API using any of the SCIM attributes mentioned in the SCIM Attribute mapping section. The SCIM API will evaluate the conditions and return a set of user matching the criteria.

The following rules apply:

The filter parameter must contain one valid boolean operator. - Each expression must contain an attribute name followed by an attribute operator. - Multiple expressions may be combined using two logical operators. - Expressions can be grouped together using "( )". - Expressions must be evaluated using the standard order of operations. - String literals must be valid JSON strings The following is a list of valid operators.

Operator	Description
`eq`	Equal
`co`	Contains
`sw`	Starts with
`ew`	Ends with
`gt`	Greater than
`ge`	Greater than equal
`lt`	Less than
`le`	Less than or equal
`and`	Logical And
`or`	Logical Or

Other examples of filtering

Paginating (Finding the first 50 users)

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?startIndex=1&count=50 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Paginating (Finding the second set of 50 users)

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?startIndex=50&count=50 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Searching users with userName

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=userName eq "jane.doe@example.com" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Searching users with either userName or familyName

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=userName eq "jane.doe@example.com" OR familyName eq "Doe" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Searching users with names like

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=givenName co "ja" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

GET /Users/{id}

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "8ab860d9-891f-4f8d-b454-9a012e001b92",
    "externalId": "",
    "userName": "",
    "name": {
        "familyName": "User",
        "givenName": "A"
    },
    "photos": [
        {
            "value": "https://static.cdn.rewardgateway.net/BrandAssets/responsive/img/avatars/200x200_default-5.png",
            "type": "photo"
        }
    ],
    "emails": [
        {
            "value": "user.a@example.com",
            "primary": true
        }
    ],
    "locale": "",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "costCenter": "",
        "organization": "",
        "division": "",
        "department": "",
        "manager": {
            "managerId": "",
            "value": ""
        }
    },
    "roles": [],
    "active": false,
    "meta": {
        "resourceType": "User",
        "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92"
    }
}

Returns a single user resource. The value of the {id} must be the user's corresponding Member ID (UUID) in Reward Gateway.

POST /Users

curl -X POST https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "name": {
        "givenName": "User",
        "familyName": "C"
    },
    "emails": [{
        "primary": true,
        "value": "user.c@example.com",
        "type": "work"
    }],
    "externalId": "ABCDE",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "costCenter": "Cost Center A",
        "organization": "Organization A",
        "division": "Division A",
        "department": "Department A",
        "manager": {
            "managerId": "K18762212"
        }
    }
}

Creates a new user on the client programme. Must include all required fields mentioned in the SCIM API Attributes Mapping section.

PATCH /USERS/{id}

curl -X PATCH https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "name": {
        "givenName": "User",
        "familyName": "ABC"
    },
    "active": true
}

Updates an existing user resource, overwriting values for specified attributes.

Attributes that are not provided will remain unchanged. Disabled users can be re-enabled by sending active attribute equal to true. The value of the {id} should be the user's corresponding Reward Gateway Member ID (UUID).

PUT /USERS/{id}

curl -X PUT https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "name": {
        "givenName": "User",
        "familyName": "A"
    },
    "emails": [{
        "primary": true,
        "value": "user.a.changed@example.com",
        "type": "work"
    }],
    "externalId": "user.a.changed@example.com",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "costCenter": "Cost Center A",
        "organization": "Organization A",
        "manager": {
            "managerId": "K18762212"
        }
    }
}

Updates an existing user resource, overwriting all values for a user even if an attribute is empty or not provided. All required attributes must be passed to this method.

If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute. Deactivated users can be re-enabled by setting the active attribute to true. The value of the {id} should be the user's corresponding Reward Gateway Member ID (UUID).

The above request will remove associated Division and Department information as it is missing from the PUT request.

DELETE /USERS/{ID}

curl -X DELETE https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Marks the user as deleted. The users shut down process will begin from the point the request is sent. This is the same as using PATCH or PUT methods and setting the active attribute to false.

POST /BULK

curl -X POST https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Bulk \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "Operations": [
        {
            "method": "POST",
            "path": "/User",
            "data": {
                "userName": "test7@test.com",
                "name": {
                    "givenName": "test",
                    "familyName": "test"
                },
                "emails": [
                    {
                        "value": "test7@test.com",
                        "primary": true
                    }
                ],
                "active": true
            }
        },
        {
            "method": "POST",
            "path": "/User",
            "data": {
                "userName": "test8@test.com",
                "name": {
                    "givenName": "test",
                    "familyName": "test"
                },
                "emails": [
                    {
                        "value": "test8@test.com",
                        "primary": true
                    }
                ],
                "active": true
            }
        }
    ]
}

Creates new users on the client programme. Must include all required fields mentioned in the SCIM API Attributes Mapping section.

Errors

Occasionally, our SCIM API will result in an error instead of the result you're expecting. This could be due to various reasons and Reward Gateway will make every attempt to respond with a descriptive error message that will help you figure out what went wrong and how to fix it. So make sure to look out for details in the error messages.

Error Code	HTTP Response Code	Description
`not_found`	404	Invalid endpoint or SCIM method.
`resource_not_found`	400	Resource you're looking for could not be found.
`no_user_found`	404	User you're looking for could not be found.
`user_exists`	409	User you are trying to provision/add already exists. Please check the userName/externalId or the Email address of the user.
`forbidden`	403	You don't have the necessary scopes to access the SCIM API.
`validation_error`	400	The SCIM Schema passed is not valid. Look for details.
`programme_invalid`	400	For your SCIM API to work, your Reward Gateway program must be set up in a specific way. If this is the error you're facing, please contact your Client Success Manager or your Implementation Specialist.
`filter_error`	400	The filter request is invalid. Look for details.

Rate Limiting

Reward Gateway APIs rely on rate limits to help provide a predictably pleasant experience for users. Rate limits are applied to all API endpoints regardless of which api you use.

Our current rate limits are set to: 180 requests for a 15 minute window. These limits are per endpoint, per unique ip address. These are also represented through headers in each response returned from the APIs.

Header	Description
`X-Rate-Limit-Limit`	Max allowed requests
`X-Rate-Limit-Remaining`	Remaining requests in the current window
`X-Rate-Limit-Reset`	Time until current window expires

Acceptable Use Policy

This Acceptable Use Policy (“Policy”) applies to the use of the Reward Gateway API.

As used in this Policy, “API” means programmatic web APIs and associated tools and documentation that Reward Gateway makes available to Reward Gateway customers and partners under this Policy.

This Policy was last updated on February 7, 2021.

Reward Gateway may change this Policy by posting an updated version on the Reward Gateway API Documentation Portal and such updates will be effective immediately.

Responsibility of the User

Users agree to use Reward Gateway’ services in a manner that is legal, appropriate and in conformity with industry standards.

Users will not use the Reward Gateway API to distribute any virus, spyware, adware, malware, or other harmful or malicious component.

Users will not use the Reward Gateway API in any way which or might overburden, impair or disrupt the Reward Gateway API or related servers or networks.

Users will not perform significant load or security testing of the Reward Gateway API without first obtaining Reward Gateway’s written consent.

Violation

If a customer’s breaches any of the terms within this Policy, Reward Gateway may immediately remove access to the Reward Gateway API.

Reward Gateway may also consider such a violation a material breach of the Client Agreement and/or other agreement governing the customer’s use of the services.

Jurisdiction

This Policy shall be governed by the laws under which the Customer ordered a Reward Gateway service and/or other agreement governing the customer’s use of the services.