Common Workflows

These workflows cover the most common integration scenarios.

---

Flow 1 — New user, assign kit for the first time

Use this flow when a user has just been imported and you need to assign their product kit.

1. Import the user

   Create or update the user record via the import endpoint.

   POST /api/import/users
   api-key: <key>
   Content-Type: application/json
   
   {
     "users": [
       {
         "email": "john.doe@example.com",
         "uber_id": 12345,
         "first_name": "John",
         "last_name": "Doe",
         "partner_name": "Adecco",
         "agency_id": "P-12345",
         "active": 1
       }
     ]
   }

   → Import Users reference

2. Resolve the internal user ID

   The import response already includes the id (see results.users[].id) — keep it for later calls. If you didn’t capture it, look it up by email instead.

   GET /api/users/find-by-email?email=john.doe@example.com
   api-key: <key>

   Response:

   { "success": true, "user_id": 84 }

   → Find User by Email reference

3. Fetch the available products (can run in parallel with step 2)

   Get the full product list so you know which product_id values to use.

   GET /api/products
   api-key: <key>

   Response:

   [
     { "id": 2,  "product_name": "Rain Pants" },
     { "id": 7,  "product_name": "Rain Jacket" },
     { "id": 14, "product_name": "Phone Holder" }
   ]

   → List Products reference

4. Add products to the user’s kit

   Call the store endpoint once per product. Repeat for each item you want to assign.

   POST /api/users/84/kit
   api-key: <key>
   Content-Type: application/json
   
   { "product_id": 7, "quantity": 1, "mandatory": true }

   POST /api/users/84/kit
   api-key: <key>
   Content-Type: application/json
   
   { "product_id": 14, "quantity": 1, "mandatory": false }

   Tip

   The endpoint is an upsert — sending the same product_id again will update the existing entry instead of creating a duplicate.

   → Add / Update Kit Product reference

---

Flow 2 — Existing user, review and update kit

Use this flow when a user already exists and you need to review or change their assigned products.

1. Resolve the internal user ID

   GET /api/users/find-by-email?email=john.doe@example.com
   api-key: <key>

   Response:

   { "success": true, "user_id": 84 }

   → Find User by Email reference

2. Get the current kit

   Retrieve what the user currently has assigned.

   GET /api/users/84/kit
   api-key: <key>

   Response:

   {
     "success": true,
     "kit": [
       { "user_id": 84, "product_id": 7,  "quantity": 1, "mandatory": true,  "product": { "id": 7,  "product_name": "Rain Jacket" } },
       { "user_id": 84, "product_id": 14, "quantity": 1, "mandatory": false, "product": { "id": 14, "product_name": "Phone Holder" } }
     ]
   }

   → Get Kit reference

3. Update or remove products as needed

   Update a product

   Send a POST with the same product_id to change quantity or mandatory. The endpoint upserts, so no separate update call is needed.

   POST /api/users/84/kit
   api-key: <key>
   Content-Type: application/json
   
   { "product_id": 14, "quantity": 2, "mandatory": true }

   → Add / Update Kit Product reference

   Remove a product

   Send a DELETE with the product_id you want to remove.

   DELETE /api/users/84/kit/14
   api-key: <key>

   → Remove Kit Product reference

---

Flow 3 — Deactivate a user

Use this flow when a user leaves or should no longer have access. Sending active: 0 via the import endpoint deactivates the account.

1. Resolve the internal user ID

   The import endpoint matches on the internal id (Boolanga ID), not uber_id. If you didn’t keep the id from the original import response, look it up by email, uber_id, or agency_id — see Flow 4, step 1 for the lookup options.

2. Send an import request with active: 0

   Include the resolved id. Only active needs to change — include the other required fields to pass validation.

   POST /api/import/users
   api-key: <key>
   Content-Type: application/json
   
   {
     "users": [
       {
         "id": 84,
         "email": "john.doe@example.com",
         "uber_id": 12345,
         "first_name": "John",
         "last_name": "Doe",
         "partner_name": "Adecco",
         "active": 0
       }
     ]
   }

   Expected response:

   {
     "success": true,
     "results": {
       "created": 0,
       "updated": 1,
       "failed": []
     }
   }

   Note

   The user record is updated, not deleted. The account can be reactivated later by sending active: 1 in a new import request with the same id.

   Caution

   Omitting id always creates a new user instead of updating the existing one.

   → Import Users reference

---

Flow 4 — Update an existing user’s details

Use this flow when you need to change a user’s data (name, partner, agency_id, etc.) but only have their email, uber_id, or agency_id, not their internal id.

1. Resolve the internal user ID

   By email

   GET /api/users/find-by-email?email=john.doe@example.com
   api-key: <key>

   Response:

   { "success": true, "user_id": 84, "uber_id": "12345", "agency_id": null }

   → Find User by Email reference

   By uber_id

   GET /api/users?uber_id=12345
   api-key: <key>

   Response:

   {
     "data": [
       { "id": 84, "uber_id": "12345", "agency_id": null, "email": "john.doe@example.com", "partner_name": "Adecco" }
     ]
   }

   → List Users reference

   By agency_id

   GET /api/users?agency_id=P-12345
   api-key: <key>

   Response:

   {
     "data": [
       { "id": 84, "uber_id": "12345", "agency_id": "P-12345", "email": "john.doe@example.com", "partner_name": "Adecco" }
     ]
   }

   → List Users reference

2. Send an import request with the resolved id

   Include id plus every required field, even the ones that aren’t changing — the request is validated as a full record, not a partial patch.

   POST /api/import/users
   api-key: <key>
   Content-Type: application/json
   
   {
     "users": [
       {
         "id": 84,
         "email": "john.doe@example.com",
         "uber_id": 12345,
         "first_name": "John",
         "last_name": "Doe-Smith",
         "partner_name": "Randstad",
         "agency_id": "P-12345",
         "active": 1
       }
     ]
   }

   Expected response:

   {
     "success": true,
     "results": {
       "created": 0,
       "updated": 1,
       "failed": []
     }
   }

   Caution

   Omitting id always creates a new user instead of updating the existing one.

   → Import Users reference

---

Flow 5 — Handle partial import failures

Use this flow when a bulk import request comes back with results.failed entries — some users saved, others didn’t.

1. Send the bulk import

   POST /api/import/users
   api-key: <key>
   Content-Type: application/json
   
   {
     "users": [
       { "email": "john.doe@example.com", "uber_id": 12345, "first_name": "John", "last_name": "Doe", "partner_name": "Adecco", "active": 1 },
       { "email": "jane.doe@example.com", "uber_id": 12345, "first_name": "Jane", "last_name": "Doe", "partner_name": "Adecco", "active": 1 },
       { "email": "sam.roe@example.com", "uber_id": 99999, "first_name": "Sam", "last_name": "Roe", "partner_name": "Unknown Partner", "active": 1 }
     ]
   }

   → Import Users reference

2. Read the response — successful and failed records are independent

   Every record in the batch is processed on its own; one failure doesn’t roll back the others.

   {
     "success": true,
     "results": {
       "created": 1,
       "updated": 0,
       "failed": [
         {
           "index": 1,
           "id": null,
           "uber_id": 12345,
           "email": "jane.doe@example.com",
           "error": "uber_id already belongs to a different user."
         },
         {
           "index": 2,
           "id": null,
           "uber_id": 99999,
           "email": "sam.roe@example.com",
           "error": "Partner not found: \"Unknown Partner\"."
         }
       ],
       "users": [
         { "index": 0, "id": 84, "uber_id": "12345", "email": "john.doe@example.com", "action": "created" }
       ]
     }
   }

3. Fix and resubmit only the failed records

   Match each failed entry back to your source data by index (position in the original request), fix the underlying issue, then resend just those records in a new request — there’s no need to resend the ones that already succeeded.

   | Error | Fix | |-------|-----| | Partner not found: "..." | Correct partner_name to match a partner that exists | | User not found for id: "..." | Drop the id if the user shouldn’t exist yet, or correct it | | Email already belongs to a different user. | Resolve the conflicting email, or add the correct id if you meant to update that user | | uber_id already belongs to a different user. | Resolve the conflicting uber_id, or add the correct id if you meant to update that user | | agency_id already belongs to a different user. | Resolve the conflicting agency_id, or add the correct id if you meant to update that user |

   → Import Users reference

---

Flow 6 — Sync your local user list with the eShop

Use this flow to keep your own system in sync with every user known to the eShop (anyone with an uber_id and/or agency_id), for example in a nightly job.

1. Page through the full user list

   Request pages in order, following next_page_url (or incrementing page) until it comes back null.

   GET /api/users?limit=200&page=1
   api-key: <key>

   GET /api/users?limit=200&page=2
   api-key: <key>

   → List Users reference

   Tip

   Narrow the sync to one partner with partner_name if you only manage a subset of users.

2. Upsert each user into your own system

   For every entry in data, store the internal id (Boolanga ID) alongside uber_id, agency_id, and email — you’ll need id for any future update via the import endpoint (see Flow 4).

   Caution

   Users are only returned while they have an uber_id and/or agency_id set. If a previously-synced user stops appearing in the list, treat that as a signal to reconcile (e.g. mark it inactive locally) rather than assuming it was deleted.

---

Flow 7 — Review exchange orders

Use this flow to review (approve or deny) pendig exchange orders.

1. Page through the full exchange orders list

   Request pages in order, following next_page_url (or incrementing page) until it comes back null.

   GET /api/v1/exchanges/orders?exchange_status=pending&limit=200&page=1
   api-key: <key>

   GET /api/v1/exchanges/orders?exchange_status=pending&limit=200&page=2
   api-key: <key>

   → List Exchange Orders reference

   Tip

   Use the exchange_status filter to retreive only the pending exchange orders.

2. Approve or deny the exchange order

   Call the review endpoint once per exchange order. Repeat for each exchange you want to review.

   POST /api/v1/exchanges/review
   api-key: <key>
   Content-Type: application/json
   
   { "order_id": 7, "status": "denied" }

   POST /api/v1/exchanges/review
   api-key: <key>
   Content-Type: application/json
   
   { "order_id": 8, "status": "approved" }

   → Review Exchange Orders reference