Ingress Users
- Alexander Conroy
This API is meant to Update basic User information for either one or more users and supports 3 different formats. Any missing data, invalid users, invalid keys or incorrect format will throw an error. Use this API to make quick updates to multiple users and meta fields in a single API call.
In TLD, User Fields are fields that are bound to the user and the account they originate on. Only users related to the current account the API is being called from can be edited. The Users API has limited fields it can update and each one has it’s own validation rules.
Endpoint: /api/ingress/users
Method: PUT
API Version Support: v1
Security Notice: Please make sure to use API | Endpoint Protection when giving this access to third party systems as API Keys are unprotected unless specified.
The proper endpoint protection to set for an API using this Endpoint is /api/ingress/users
Data Formats Supported
form-data, x-www-form-urlencoded Form Parameters or JSON Body with Content-Type: application/json set.
Response Codes
200: Success and Warnings
400: Error
Update Fields Allowed
first_name, last_name, middle_name, alias, nick_name, employee_id, agency_id, vendor_id, status_id, email, extension
Notice: When updating email addresses, if the email address is different, users will have to re-verify their email and MFA in again.
Update Format 1: Users as Objects with Key->Value Object to Update
Parameter | Required | Format | Description | Notes |
|---|---|---|---|---|
| ✓ | object - Object of User ID Keyed Objects with Field → Value Pairs | The Object that contains the User Keys and Values to Update. Fields Can be mixed but all must be valid. | Must have at least 1 valid User ID. Invalid User ID’s will throw an error. |
| ✓ | numeric string | Specified the User being Updated. | Any Invalid Fields in any object will throw an error. |
| ✓ | string|int | Value for the User Field you want to Update. |  |
JSON Object
{
"users": {
"{user_id}": {
"{field_name}": "{field_value}",
"{field_name}": "{field_value}"
},
"{user_id}": {
"{field_name}": "{field_value}",
"{field_name}": "{field_value}"
}
}
}Update Format 2: Array of Full User, Field and Value Objects. An Array of Format 3 Objects
Parameter | Required | Format | Description | Notes |
|---|---|---|---|---|
| ✓ | array - Array of User ID, Field and Value Objects | This allows you to use Format 3 to Bulk Update Multiple Users for Multiple Fields individually. | Must have at least 1 valid User, and all fields must be valid. |
| ✓ | integer | Specified the User being Updated | Any Invalid Users in any object will throw an error. |
| ✓ | string | Name of the Field you want to Update. | Any Invalid Fields in any object will throw an error. |
| ✓ | string|int | Value for the Field you want to Update. |  |
JSON Object
{
"fields": [
{ "user_id": "{user_id}", "field": "{field_name}", "value": "{field_value}" },
{ "user_id": "{user_id}", "field": "{field_name}", "value": "{field_value}" },
{ "user_id": "{user_id}", "field": "{field_name}", "value": "{field_value}" },
{ "user_id": "{user_id}", "field": "{field_name}", "value": "{field_value}" }
]
}Update Format 3: 1 User 1 Field Update
Parameter | Required | Format | Description | Notes |
|---|---|---|---|---|
| ✓ | integer | Specified the User being Updated | Any Invalid Users in any object will throw an error. |
| ✓ | string | Name of the Field you want to Update. | Any Invalid Fields in any object will throw an error. |
| ✓ | string|int | Value for the Field you want to Update. |  |
JSON Object
{
"user_id": "{user_id}", "field": "{field_name}", "value": "{field_value}"
}Errors Possible
Error | Resolution |
|---|---|
No API ID Provided | Check API ID in Header or Parameters. See API | Using API ID and API Key |
No API Key Provided | Check API Key in Headers or Parameters. See API | Using API ID and API Key |
When passing Users, you must provide the object key of the User ID as an object with fields and values. {missing_fields_list} Fields were missing keys or user ids. | Check |
When passing Fields, you must provide user_id, field and value. {missing_fields_list} Fields were missing keys. | check |
`You must provide user_id, field and value, a key was missing . | Check |
No fields found to update, aborting | Check |
No users found to update, aborting | Check |
Some field arguments passed are not allowed or do not exist for update, aborting | Check |
Unable to find all users to update, found {found_users} / {user_count} for requested update, aborting | Check |