Use the update_users_and_vehicles API call to create or update a user or vehicle object. To use this API call, supply an array containing the account_id for up to 10 objects along with any fields that require an update, as in the following example.
POST /station/v4/update_users_and_vehicles
{
"users": [
{
"account_id": "jeanm@example.com",
"expiration_date":"2020-09-30"
},
{
"account_id": "mariem@example.com",
"expiration_date":"2020-09-30"
},
{
"account_id": "pierrem@example.com",
"expiration_date":"2020-09-30"
}
]
}Each update_users_and_vehicles request is treated as a single transaction. If any object in the request cannot be processed, the entire call will fail and the reason for the failure will be reported in the resulting error response.
When updating a user or vehicle account, include only the properties you want to update, and do NOT include properties with null values. Null values will overwrite any existing value for the property.
Results
If a matching object is found when the call is made, the system will assume the purpose of your call was to update that object and will function as an update. The system cannot determine whether your intent is to create or update, and will decide which function to use based on whether the identifier provided is found to exist already. This could result in a new object replacing or merging with an existing object.
When this call is made, one of the following behaviors is triggered:
No identifier found: If any object in the request is missing an identifier, the system cannot process the object and throws an error for the entire request, indicating which object is missing its identifier. The system stops the first time a missing identifier is found. If more than one object is missing its identifier, subsequent attempts to run the request will highlight them.
Invalid identifier found: If any object in the request uses the wrong identifier, the system cannot process the object. Identifiers set by CMT are integers while all other identifiers are strings.
Non-existing CMT identifier found: The
short_user_idandshort_vehicle_idcan only be set by CMT. If an object in the request payload contains one of these identifiers, the system automatically assumes the request is trying to update that object. If no existing object has that identifier, the system cannot process that portion of the request payload and throws an error for the entire request indicating which object caused the problem.Existing valid identifier found: When a valid identifier is supplied, the system checks to see if the identifier matches an existing object. If it matches an existing identifier, the existing object is updated with the changes supplied in that portion of the request payload.
New valid identifier found: When a valid identifier is supplied, the system checks to see if the identifier matches an existing object. If no matching object is found, a new object is created with the data supplied in that portion of the request payload.
Example use cases
Below are examples of use cases for the update_users_and_vehicles call.
Updating one or more properties on a user account
Adam is a driver who entered your safe driving program two weeks ago. Following company procedures, a user account was created for Adam when he was entered into the system. However, whoever entered Adam into the system forgot to set the start_recording_date, which is the date your telematics-enabled app will start recording Adam’s trips. To correct this and set the start date, make the following call:
POST /station/v4/update_users_and_vehicles
{
"users": [
{
"account_id": “5ed9d400-55cd-11e7-9598-0800200c9a66”,
"start_recording_date": “2020-10-12T13:55:22Z”
}
]
}The request succeeds and returns the following user object in the response:
{
"users": [
{
"short_user_id": 1071077,
"account_id": “5ed9d400-55cd-11e7-9598-0800200c9a66”,
"start_recording_date": “2020-10-12T13:55:22Z”
}
]
}Note that null fields are not returned in the response.
For additional details, visit the HELP CENTER by tapping on HELP from the Drivewell Portal.
0 comments