The Unimarket User REST API allows for the real-time synchronization of user data between your internal systems (like an HRIS or ERP) and Unimarket. This interface supports single-user updates as well as initial bulk loads by processing one request per user.

REST API Operations

The API provides three primary methods to manage user lifecycles.

• Get User (GET): Fetches a user by their username. This is often used as a preliminary check to determine if a user exists before deciding whether to use a Create or Update operation.

• Create User (POST): Adds a new user record. If you do not provide a unique id (UUID), Unimarket will generate one for you.

• Update User (PUT): Modifies an existing user record. This operation requires the Unimarket User UUID (id) to identify the specific record to be changed.

• The URL for the API is: api.unimarket.com (or .co.nz, com.au)

Message Details

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"

}

 ]

}

Authentication & Standard Headers

To ensure secure communication, Unimarket requires two specific HTTP headers for every request. These headers serve as your credentials and must be included for the upload to be processed.

Security Tip: The API Key can be locked to specific IP addresses. By restricting it to your server's IP, you ensure that even if the key is leaked, unauthorized requests from other locations will be rejected.

Understanding HTTP Status Codes

Unimarket uses standard HTTP status codes to communicate the outcome of your request. Always check these codes in your integration logic to handle errors effectively.

• 200 (Success): The operation was completed successfully.

• 400 (Bad Request): The request failed due to incorrect data or formatting. A descriptive error message is usually included in the response body.

• 401 (Unauthorized): Authentication failed. Check your Unimarket-Account-ID and Unimarket-API-Key.

• 404 (Not Found): Returned during a GET or PUT if the specified user does not exist in Unimarket.

Core Operations

1. Get User (GET)

Used to retrieve the current JSON profile of a specific user.

• Endpoint: /v1/users/username/{username}

• Logic: If the user is found, Unimarket returns the full user object. If not, a 404 is returned.

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> 

2. Create User (POST)

Used to add a new user to the Unimarket community.

• Endpoint: /v1/users

• ID Handling: The id field is optional. If you provide one, it must be unique. If omitted, Unimarket generates a unique ID and returns it in the response.

• Response: Unimarket returns the finalized JSON user object. This is important as some fields may be modified by system constraints (e.g., auto-added roles or trimmed text).

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>

3. Update User (PUT)

Used to modify an existing user's information.

• Endpoint: /v1/users

• Identification: The system uses the id field within the JSON body to identify which record to update.

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 Security & IP Whitelisting

A Unimarket API Key functions similarly to a highly secure password for your integration. It is specifically generated during the integration setup process to authorize RESTful requests to the Unimarket platform.

Security via IP Whitelisting

To prevent unauthorized access, Unimarket allows you to tie an API Key to specific Trusted IP Addresses. This creates a "network perimeter" around your integration.

• Restricted Access: When whitelisting is enabled, Unimarket only accepts requests if they originate from your pre-approved server IP addresses.

• Malicious Blocking: Even if your API Key is accidentally exposed (e.g., leaked in a code repository). A malicious actor would be unable to use it. Because their requests would originate from an unapproved IP, resulting in an immediate rejection.

Key Management Best Practices

Because an API Key grants significant access to your Unimarket community, follow these security protocols:

• Confidentiality: Store your API Key in secure environment variables or a secret management tool. Never hardcode keys directly into your integration scripts.

• Static IPs: Ensure your organization uses Static IPs for its integration servers. If your IP address is dynamic (changes frequently), the whitelisting feature may cause intermittent connection failures.

• Regular Rotation: As a preventive measure, it is recommended to regularly generate new keys and deactivate old ones, similar to updating a corporate password.

Requesting Your Key

Since API Keys are not generated by users, you must coordinate with the Unimarket team during your Integration Setup:

1. Contact Support: Reach out to your Unimarket technical account manager or support representative.

2. Provide IP Details: Provide the static IP addresses of the servers, that will be making the API calls (e.g., your ERP or middleware server).

3. Secure Delivery: Unimarket will generate and securely transmit the key to your authorized administrator.

POST /v1/users HTTP/1.1
Host: api.unimarket.com
Content-Type: application/json; charset=utf-8
Unimarket-Account-ID: YOUR_ACCOUNT_ID
Unimarket-API-Key: YOUR_SECRET_API_KEY

{
  "username": "jsmith001",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@school.edu",
  "enabled": true,
  "roles": [{ "code": "COMMUNITY_BUYER" }]
}