Customers can send Unimarket new and updated users in real time via a JSON REST interface. It is also possible to submit an initial bulk load of users through the same interface (one user per request).
The JSON format is used by all the below operations. Get User responds with it; the other operations expect it as input.
Unimarket exposes three operations through this REST interface:
- Get User - Fetch an existing user by username. The Customer can use this for users for which it does not know the Unimarket User UUID to determine if it should send a create or update request
- Create User - Create a new user. The Customer can use this for new users after calling GET to confirm the user does not yet exist in Unimarket
- Update User - Update an existing user. The Customer can use this for users for which it already knows the Unimarket User UUID.
The URL for the API is: api.unimarket.com (or .co.nz, com.au)
Message Details
|
Name |
Data Type |
Description |
|
id |
string(255) |
Unimarket unique ID for a user (stays the same even if the username changes). Unimarket will generate this ID if it is not provided for the create operation but the call needs to ensure it is unique and it cannot be changed. |
|
username |
string(255) |
Username |
|
externalId |
string(255) |
An alternative username. This will hold the user’s external ID. |
|
firstName |
string(255) |
The user’s first name. |
|
lastName |
string(255) |
The user’s last name. |
|
displayName |
string(255) |
A display name to show when searching for buyers to reassign to. This could include the buyer’s name, email address and/or default location code |
|
|
string(255) |
The user’s email address. |
|
phone |
string(255) |
The user’s phone number. |
|
enabled |
boolean |
Users whose accounts are not enabled will be prevented from logging into Unimarket. |
|
organisationsUnits |
array of object |
One per Organisation Unit. These must be unique. |
|
organisationsUnits.code |
string(255) |
Organisation Unit codes, each of which is a string(255) |
|
roles |
array of object |
One per role. |
|
roles.code |
string(255) |
One of the role values defined in User Detail Request in Unimarket Helpdesk. |
|
buyerGroups |
array of object |
One per buyer group that the user is a member of. These control a user’s access to suppliers and catalogues. |
|
buyerGroups.code |
string(255) |
Buyer Groups |
|
attributes |
array of object |
One per custom attribute |
|
attributes.name |
string(20) |
Name of the attribute |
|
attributes.value |
string(20) |
Value of the attribute |
|
approverGroups |
array of object |
One per approver group that the user is a member of. |
|
approverGroups.code |
string(255) |
Approver Groups |
Example message
{
"id": "278d1da1-3ebd-11e8-9726-9cb6d0f65f6c",
"username": "jsmith001",
"externalId": "john-smith-123",
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith john.smith School Administrative Officer",
"email": "john.smith@community.com",
"phone": "(00) 1234-5678",
"enabled": true,
"organisationUnits": [
{
"code": "1010"
},
{
"code": "2256"
}
],
"roles": [
{
"code": "COMMUNITY_BUYER"
},
{
"code": "COMMUNITY_RFQ_CREATE"
}
],
"buyerGroups": [
{
"code": "GENERAL"
},
{
"code": "CORPORATE"
}
],
"attributes": [
{
"name": "Contractor",
"value": "true"
}
]
}
Standard Headers
HTTP Headers will be required as part of the message to identify the source of message (Community). Two headers will be required. The user upload will only be processed if both these headers are correct.
- Unimarket-Account-ID, this value will be supplied by Unimarket and is used in all REST messages sent to Unimarket as a unique (but not secret) identifier for the Customer in Unimarket.
- Unimarket-API-Key, Similar to a password. The API Key will be generated inside Unimarket and linked to this customer. This can also be restricted to only work from specific IP addresses.
HTTP Status Codes
Unimarket will respond with an HTTP status code indicating success or failure of the operation.
- 200 for success
- 400 for a failure, along with a message describing the reason for failure.
- 401 for an authentication failure.
- 404 for a GET or PUT (update) request for a user that does not exist.
Get User Operation
The Get User operation will be a simple GET request with the requested username to which Unimarket will respond with either a JSON representation of the user or a 404 error code if the user does not exist.
A sample Get User JSON GET request will look similar to this:
GET /v1/users/username/jsmith001 HTTP/1.1
Host: api.unimarket.com
Unimarket-Account-ID: <account id>
Unimarket-API-Key: <api key>
Create User Operation
The Create User operation will be a POST request with a JSON user in the body of the message. The id field is optional, if it is provided it must be unique, if it is not provided, Unimarket will generate a unique id. Unimarket will respond with the full JSON of the newly created user. Most of this will be the same data just uploaded but there may be additional fields and potentially some data may have been modified as result of constraints (e.g. non-critical fields could be trimmed rather than rejecting the request) or business rules (e.g. all users might automatically get a role added) Importantly, the JSON response will contain the id field that Customer can remember for future updates.
A sample Create User POST request will look similar to this:
POST /v1/users HTTP/1.1
Host: api.unimarket.com
Content-Type: application/json; charset=utf-8
Content-Length: <size of json file>
Unimarket-Account-ID: <account id>
Unimarket-API-Key: <api key>
<JSON DATA>
Update User Information
The Update User operation will be a PUT request with a JSON user in the body of the message. The user to update will be identified by the id field in the JSON message.
A sample Update User PUT request will look similar to this:
PUT /v1/users HTTP/1.1
Host: api.unimarket.com
Content-Type: application/json; charset=utf-8
Content-Length: <size of json file>
Unimarket-Account-ID: <account id>
Unimarket-API-Key: <api key>
API Key
Unimarket will generate a unique API key that is specific to the customer.
Unimarket needs to generate the key for you which will be done during integration setup.
This API Key can be linked to a specific IP address(es) and then only requests from those address(es) will be accepted for the API Key, others will be rejected. By configuring this with the IP address of the Customer, only requests coming from that server will be accepted.