Users Endpoint

Endpoint Actions

Create Record

POST /v2/users

{
    "user": {
        "primary_location_id":"{{location_id}}",
        "branding_domain_id":"{{branding_domain_id}}",
        "first_name":"test",
        "last_name":"user",
        "email":"testuser@test.com",
        "username":"{{user_name}}",
        "password":"Password123!",
        "user_type_id":"200",
        "user_api_key": "jfg9j8ashf83hrisdjw983hu4rbfsd8h3" // Optional
    }
}

{
    "user": {
        "id": "{id}",
        "domain_id": "{branding_domain_id}",
        "contact_id": "{contact_id}",
        "username": "{user_name}",
        "email": "testuser@test.com",
        "user_type_id": 200,
        "locale": "en-US",
        "status_id": 1,
        "tz": "America/New_York",
        "login_attempts": null,
        "current_login_ip": "",
        "current_login": null,
        "last_login_ts": 1518627249,
        "requires_new_password": "",
        "created_ts": 1422030616,
        "modified_ts": 1422030616,
        "primary_location_id": "{location_id}",
        "branding_domain_url": "{branding_domain_url}",
        "created_user_id": "11e7a84asdf098as768b2661a9a",
        "terms_condition_id": "20136422.00",
        "terms_accepted_ts": 1518627249,
        "terms_agree_ip": "24.255.177.186",
        "current_date_time": "2019-03-11T10:38:26-0700",
        "ui_prefs": {
            "entry_page": "dashboard",
            "page_size": 15,
            "report_export_type": "csv",
            "process_method": "virtual_terminal",
            "default_terminal": "11e7ce9sd8f9d388281db01"
        },
        "user_api_key": null,
        "user_hash_key": null,
        "first_name": "test",
        "last_name": "user",
        "address": null,
        "city": null,
        "state": null,
        "zip": null,
        "account_number": null,
        "date_of_birth": null,
        "email_trx_receipt": false,
        "company_name": null,
        "home_phone": null,
        "cell_phone": null,
        "office_phone": null,
        "office_ext_phone": null,
        "_links": {
            "self": {
                "href": "{url}/v2/users/{id}"
            }
        }
    }
}

Generate User API Key

For more information about using user_api_key please take a look at the Authentication page.

IMPORTANT: If you want to use a custom user_api_key you need to provide this value during the Create Record POST. If you need to to use a user_api_key after the user is already created there is a specific endpoint that can be used to generate a user_api_key. Details about using this other endpoint to generate a user_api_key can be found below.

POST /v2/users/{id}/generateuserapikey

Sample Response

{
    "user": {
        "user_api_key": "234bas8dfn8238f923w2"
    }
}

Update Record

PUT /v2/users/{id}

{
    "user": {
        "first_name":"John"
        ... // Other fields to update
    }
}

{
    "user": {
        "id": "{id}",
        "domain_id": "{branding_domain_id}",
        "contact_id": "{contact_id}",
        "username": "{user_name}",
        "email": "testuser@test.com",
        "user_type_id": 200,
        "locale": "en-US",
        "status_id": 1,
        "tz": "America/New_York",
        "login_attempts": null,
        "current_login_ip": "",
        "current_login": null,
        "last_login_ts": 1518627249,
        "requires_new_password": "",
        "created_ts": 1422030616,
        "modified_ts": 1422030616,
        "primary_location_id": "{location_id}",
        "branding_domain_url": "{branding_domain_url}",
        "created_user_id": "11e7a84asdf098as768b2661a9a",
        "terms_condition_id": "20136422.00",
        "terms_accepted_ts": 1518627249,
        "terms_agree_ip": "24.255.177.186",
        "current_date_time": "2019-03-11T10:38:26-0700",
        "ui_prefs": {
            "entry_page": "dashboard",
            "page_size": 15,
            "report_export_type": "csv",
            "process_method": "virtual_terminal",
            "default_terminal": "11e7ce9sd8f9d388281db01"
        },
        "user_api_key": null,
        "user_hash_key": null,
        "first_name": "John",
        "last_name": "user",
        "address": null,
        "city": null,
        "state": null,
        "zip": null,
        "account_number": null,
        "date_of_birth": null,
        "email_trx_receipt": false,
        "company_name": null,
        "home_phone": null,
        "cell_phone": null,
        "office_phone": null,
        "office_ext_phone": null,
        "_links": {
            "self": {
                "href": "{url}/v2/users/{id}"
            }
        }
    }
}

Update Password

PUT /v2/users/{id}

This endpoint can be used to change a users password. When changing a users password the following criteria apply:

If the logged in user changing the password of another user, the password is only good for one time use.
If the logged in user is changing their own password, the old password field must be supplied.

Below is an example of a user changing another users password which is good for one time use.

{
    "user": {
        "old_password": "Password123!",
        "password": "New_Password123!
    }
}

{
    "user": {
        "id": "{id}",
        "domain_id": "{branding_domain_id}",
        "contact_id": "{contact_id}",
        "username": "{user_name}",
        "email": "testuser@test.com",
        "user_type_id": 200,
        "locale": "en-US",
        "status_id": 1,
        "tz": "America/New_York",
        "login_attempts": null,
        "current_login_ip": "",
        "current_login": null,
        "last_login_ts": 1518627249,
        "requires_new_password": "",
        "created_ts": 1422030616,
        "modified_ts": 1422030616,
        "primary_location_id": "{location_id}",
        "branding_domain_url": "{branding_domain_url}",
        "created_user_id": "11e7a84asdf098as768b2661a9a",
        "terms_condition_id": "20136422.00",
        "terms_accepted_ts": 1518627249,
        "terms_agree_ip": "24.255.177.186",
        "current_date_time": "2019-03-11T10:38:26-0700",
        "ui_prefs": {
            "entry_page": "dashboard",
            "page_size": 15,
            "report_export_type": "csv",
            "process_method": "virtual_terminal",
            "default_terminal": "11e7ce9sd8f9d388281db01"
        },
        "user_api_key": null,
        "user_hash_key": null,
        "first_name": "John",
        "last_name": "user",
        "address": null,
        "city": null,
        "state": null,
        "zip": null,
        "account_number": null,
        "date_of_birth": null,
        "email_trx_receipt": false,
        "company_name": null,
        "home_phone": null,
        "cell_phone": null,
        "office_phone": null,
        "office_ext_phone": null,
        "_links": {
            "self": {
                "href": "{url}/v2/users/{id}"
            }
        }
    }
}

View Single Record

GET /v2/users/{id}

{
    // Empty Payload - Nothing Needed Here
}

{
    "user": {
        "id": "{id}",
        "domain_id": "{branding_domain_id}",
        "contact_id": "{contact_id}",
        "username": "{user_name}",
        "email": "testuser@test.com",
        "user_type_id": 200,
        "locale": "en-US",
        "status_id": 1,
        "tz": "America/New_York",
        "login_attempts": null,
        "current_login_ip": "",
        "current_login": null,
        "last_login_ts": 1518627249,
        "requires_new_password": "",
        "created_ts": 1422030616,
        "modified_ts": 1422030616,
        "primary_location_id": "{location_id}",
        "branding_domain_url": "{branding_domain_url}",
        "created_user_id": "11e7a84asdf098as768b2661a9a",
        "terms_condition_id": "20136422.00",
        "terms_accepted_ts": 1518627249,
        "terms_agree_ip": "24.255.177.186",
        "current_date_time": "2019-03-11T10:38:26-0700",
        "ui_prefs": {
            "entry_page": "dashboard",
            "page_size": 15,
            "report_export_type": "csv",
            "process_method": "virtual_terminal",
            "default_terminal": "11e7ce9sd8f9d388281db01"
        },
        "user_api_key": null,
        "user_hash_key": null,
        "first_name": "test",
        "last_name": "user",
        "address": null,
        "city": null,
        "state": null,
        "zip": null,
        "account_number": null,
        "date_of_birth": null,
        "email_trx_receipt": false,
        "company_name": null,
        "home_phone": null,
        "cell_phone": null,
        "office_phone": null,
        "office_ext_phone": null,
        "_links": {
            "self": {
                "href": "{url}/v2/users/{id}"
            }
        }
    }
}

View Self Record

GET /v2/users/me

{
    // Empty Payload - Nothing Needed Here
}

{
    "user": {
        "id": "{id}",
        "domain_id": "{branding_domain_id}",
        "contact_id": "{contact_id}",
        "username": "{user_name}",
        "email": "testuser@test.com",
        "user_type_id": 200,
        "locale": "en-US",
        "status_id": 1,
        "tz": "America/New_York",
        "login_attempts": null,
        "current_login_ip": "",
        "current_login": null,
        "last_login_ts": 1518627249,
        "requires_new_password": "",
        "created_ts": 1422030616,
        "modified_ts": 1422030616,
        "primary_location_id": "{location_id}",
        "branding_domain_url": "{branding_domain_url}",
        "created_user_id": "11e7a84asdf098as768b2661a9a",
        "terms_condition_id": "20136422.00",
        "terms_accepted_ts": 1518627249,
        "terms_agree_ip": "24.255.177.186",
        "current_date_time": "2019-03-11T10:38:26-0700",
        "ui_prefs": {
            "entry_page": "dashboard",
            "page_size": 15,
            "report_export_type": "csv",
            "process_method": "virtual_terminal",
            "default_terminal": "11e7ce9sd8f9d388281db01"
        },
        "user_api_key": null,
        "user_hash_key": null,
        "first_name": "test",
        "last_name": "user",
        "address": null,
        "city": null,
        "state": null,
        "zip": null,
        "account_number": null,
        "date_of_birth": null,
        "email_trx_receipt": false,
        "company_name": null,
        "home_phone": null,
        "cell_phone": null,
        "office_phone": null,
        "office_ext_phone": null,
        "_links": {
            "self": {
                "href": "{url}/v2/users/{id}"
            }
        }
    }
}

View Record List

GET /v2/users

Note: Filters can be used to search for Users by including the columns you want to filter on as URL parameters. i.e. /v2/users?field=value&field2=value2

{
    // Empty Payload - Nothing Needed Here
}

{
    "users": [
        {
            "id": "{id}",
            "domain_id": "{branding_domain_id}",
            "contact_id": "{contact_id}",
            "username": "{user_name}",
            "email": "testuser@test.com",
            "user_type_id": 200,
            "locale": "en-US",
            "status_id": 1,
            "tz": "America/New_York",
            "login_attempts": null,
            "current_login_ip": "",
            "current_login": null,
            "last_login_ts": 1518627249,
            "requires_new_password": "",
            "created_ts": 1422030616,
            "modified_ts": 1422030616,
            "primary_location_id": "{location_id}",
            "branding_domain_url": "{branding_domain_url}",
            "created_user_id": "11e7a84asdf098as768b2661a9a",
            "terms_condition_id": "20136422.00",
            "terms_accepted_ts": 1518627249,
            "terms_agree_ip": "24.255.177.186",
            "current_date_time": "2019-03-11T10:38:26-0700",
            "ui_prefs": {
                "entry_page": "dashboard",
                "page_size": 15,
                "report_export_type": "csv",
                "process_method": "virtual_terminal",
                "default_terminal": "11e7ce9sd8f9d388281db01"
            },
            "user_api_key": null,
            "user_hash_key": null,
            "first_name": "test",
            "last_name": "user",
            "address": null,
            "city": null,
            "state": null,
            "zip": null,
            "account_number": null,
            "date_of_birth": null,
            "email_trx_receipt": false,
            "company_name": null,
            "home_phone": null,
            "cell_phone": null,
            "office_phone": null,
            "office_ext_phone": null,
            "_links": {
                "self": {
                    "href": "{url}/v2/users/{id}"
                }
            }
        },
        ... // Other Users Here
    ],
    "meta": {
        "pagination": {
            "links": {
                "self": {
                    "href": "{url}/v2/users?page_size=3&page=1"
                },
                "next": {
                    "href": "{url}/v2/users?page_size=3&page=2"
                },
                "last": {
                    "href": "{url}/v2/users?page_size=3&page=3"
                }
            },
            "totalCount": 8,
            "pageCount": 3,
            "currentPage": 0,
            "perPage": 3
        },
        "sort": {
            "attributes": {
                "id": "desc"
            }
        }
    }
}

Delete Record

DELETE /v2/users/{id}

{
    // Empty Payload - Nothing Needed Here
}

Conditional JSON Response on HTTP Response Code:

204 - Success, User was deleted.
409 - Fail, User was not deleted. Validation error provided.

Fields

Name	Format	Max.	Allowed on POST	System Generated	Comments
id	string	36		✔	ID
account_number	string	32	✔		Account Number
address	string	64	✔		Address
branding_domain_url	string	64			system generated
cell_phone	string	10
city	string	100			City Name
company_name	string	64
contact_id	string	36		✔	Contact ID
created_ts	integer	10		✔	Created Time Stamp
created_user_id	string	36
current_date_time	string			✔	Current date and time
current_login	date			✔	Datetime
current_login_ip	string	64		✔	Current Login IP
date_of_birth	yyyy-mm-dd				Datetime
domain_id	string	36		✔	Payment method
email	string	128	✔		Email
email_trx_receipt	boolean		✔		Set to true to email transaction receipts
home_phone	string	10
first_name	string	64			First Name
last_login_ts	integer				Last login timestamp
last_name	string	64			Last Name
locale	string	8			Locale
login_attempts	integer				Login attempts
modified_ts	integer	10		✔	Modified Time Stamp
office_phone	string	10
office_ext_phone	string	10
primary_location_id	string	36		✔	Primary Location ID
requires_new_password	string	1			Required new password
state	string	100			State name
status_id	integer			✔	"1" indicates an "active" status for the User record, and "0" indicates an inactive User record.
terms_accepted_ts	integer			✔	Timestamp of when terms were accepted
terms_agree_ip	string				IP address of client machine from which terms were accepted
terms_condition_id	string	36			UUID for set of terms and conditions
tz	string	30			Time Zone
ui_prefs	JSON			✔	Contains various User preferences in JSON object
ui_prefs[entry_page]	string			✔	Default: "dashboard"
ui_prefs[page_size]	integer			✔	Default: 15
ui_prefs[report_export_type]	string			✔	Default: "csv"
ui_prefs[process_method]	string			✔	Default: "virtual_terminal"
ui_prefs[default_terminal]	string	36		✔	Default: {Default terminal UUID from User's Location}
username	string	64		✔	User name used for logging into UI depending on integration
user_api_key	string	64	✔	✔	Used for authentication with certain integration types
user_hash_key	string			✔	Used for authentication with certain integration types
user_type_id	integer	8			Used to identify role/permissions. Users with user_type_id of 250 are labelled as Client Admins in UI.
zip	string	10			Zip code