User - Create / Update

Purpose

To insert or update a User which your API Credentials has access to. An internal_user_id (ie; the ID of the object on your internal system) is required as this endpoint uses that ID to dynamically perform either an INSERT (if a new ID) or an UPDATE (if an existing ID).

Included in this endpoint is the ability to set an access rule for each Account the user has access to:

Account Access
Permission Group
Status (active/archived)

info

A user can be created at the "Parent" or "Child" Account level. A "Parent" user has access to all "Child" accounts.

Request

Endpoint

POST /user

Authentication

Include your API Key within the x-api-key header as described here.

Request Body Parameters

NOTE: The internal_user_id in the request is used to apply "upsert" logic - ie; if a matching record is found it will perform an update and if not it will perform an insert. If a user already exists on Incentify then you will not be able to update their current information and your user access updates will only impact that related to your account(s). Their information and user access to their existing accounts will not be impacted.

The following table lists the parameters supported in the JSON POST payload.

Required Request Parameters

* are required only on create.
** are required every request (both create and update), but the value is only set upon creation (ie; can not be changed).
*** are required only on create and can never be updated.
**** have custom/complex logic, which is defined as footnotes to the table below.
Marked with NO asterisk are optional parameters. If you do not include them in an update request then the current value will be preserved.

Parameter	Type	Definition
first_name *	string	First Name of the User.
last_name *	string	Last Name of the User.
internal_user_id **	string	The unique ID of of the User from your Internal System.
internal_auth_id	string	Only necessary if the account is configured to use SSO and email address is not the identify. This is the unique auth ID of the user passed through in the claims of the SSO flow.
email *	string	Email of the User. If the email address has a domain that matches a pre-configured, white-listed domain then the user will be considered an "internal" user. Otherwise, it will be set as a "client/external" user.
company_name *	string	The name of the primary company the user is affiliated with. This has no access rules tied to it. It is simply used in various lists to help distinguish the "source" of the user (ie; when assigning tasks to a user, for example) in case the user has acccess to multiple accounts.
account_access ****	array	Array container of one or more account access definitions for this user. If you no longer include an account_access object in this array that you once did then that account access will be automatically set to `archived` and that user will no longer have access.
account_access[].internal_account_id	string	The internal account ID of the Account to give this user access to. If it is a child account, then that ID was set in the "Account > Child Create/Update POST endpoint). If it is the parent account, then supply the hard coded value "incentify_parent" as the internal ID.
account_access[].user_permission_group_id	int	Pass in the snake case name of the permission group (ie; if a permission group on Incentify is named "Incentives Manager" then pass in "incentives_manager")
account_access[].user_status	enum	Can either be `active` or `archived`.

account_access ****

As mentioned in account_access array above, if you no longer include an account_access object in this array that you once did then that account access will be automatically set to archived and that user will no longer have access to the Account.
A user must either have account access to one or more children accounts, or one and only one parent account. (or empty account access effectively archiving them).
Parent user access can ONLY be granted to users with email addresses that map to a pre-configured whitelist of domains.

Request Body Example 1 - Adding User to Child Account(s)

{
    "first_name":"Jane",
    "last_name":"Shaw",
    "internal_user_id":"XXXXXXX-XXX-XXXXXXXX1",
    "email":"[email protected]",
    "company_name":"Big Industries Inc.",
    "account_access": [
        {
            "internal_account_id":"child_account_1893",
            "user_permission_group_id": "incentives_manager",
            "user_status":"active"
        },
        {
            "internal_account_id":"child_account_1899",
            "user_permission_group_id": "admin",
            "user_status":"active"
        }
    ]
}

Request Body Example 2 - Adding User to Parent Account

{
    "first_name":"Megan",
    "last_name":"Mulah",
    "internal_user_id":"XXXXXXX-XXX-XXXXXXXX2",
    "email":"[email protected]",
    "company_name":"Big Advisors, Inc.",
    "account_access": [
        {
            "internal_account_id":"incentify_parent",
            "user_permission_group_id": "admin",
            "user_status":"active"
        }
    ]
}

Request Body Example 3 - Archiving User Access

{
    "first_name":"Jane",
    "last_name":"Shaw",
    "internal_user_id":"XXXXXXX-XXX-XXXXXXXX1",
    "email":"[email protected]",
    "company_name":"Big Industries Inc.",
    "account_access": []
}

Note above that "account_access" is an empty array.

Response

If successful, this method returns a response body with the following structure:

Response Body

{
    "code":200,
    "success":1,
    "data": {
        User Resource here (See "User - Overview" page)
    },
    "errors": [],
    "meta": {},
    "links": {}
}

Properties

The following table defines the properties that appear in this resource:

Key	Type	Definition
code	integer	HTTP Status Code (ie; 200, 403, etc).
success	integer	Either 1 (success) or 0 (fail).
data	object	User updated is returned. The data structure of the User is a User Resource.
errors	object	If the request fails, this will contain information about the error.
meta	object	Contains information about pagination and total record count.
links	object	Contains pre-built links for forward/backward pagination.

Purpose​

Request​

Response​

Purpose

Request

Response