{"openapi":"3.1.0","info":{"title":"Firstbase API Specification Beta","description":"Integration endpoints for Firstbase","version":"0.1.0"},"servers":[{"url":"/","description":"Default"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Inventory Orders","description":"Create and manage inventory orders"},{"name":"Inventory","description":""},{"name":"Packages","description":""},{"name":"Catalog","description":""},{"name":"Orders","description":""},{"name":"People","description":"Manage the users of Firstbase for your organization. API follows the SCIM standard.","externalDocs":{"url":"https://scim.cloud/"}},{"name":"Returns","description":"Return and Replacements"}],"paths":{"/scim/v2/Users/{id}":{"get":{"tags":["People"],"summary":"Get a user by id","operationId":"getUserById","parameters":[{"name":"id","in":"path","description":"Unique id of the user","required":true,"schema":{"type":"string"}},{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","required":false,"schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","required":false,"schema":{"type":"string"}}],"responses":{"404":{"description":"Unable to find user","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"User has been found","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}}}}},"put":{"tags":["People"],"summary":"Update an existing user within Firstbase","operationId":"updateUser","parameters":[{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","required":false,"schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}},"required":true},"responses":{"404":{"description":"Unable to find person, organization or package","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Unable to update user due to conflict","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"409":{"summary":"A user with this userName already exists","description":"409","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource already exists","scimType":"uniqueness","status":"409"}}}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"User has been updated","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}}}}},"delete":{"tags":["People"],"summary":"Delete a user from Firstbase","description":"Deleting a User will start the Offboarding process for the user. This is a SOFT delete, in which the user will still have access to the Firstbase platform until offboarding has completed","operationId":"deleteUser","parameters":[{"name":"id","in":"path","description":"Unique id of the user","required":true,"schema":{"type":"string"}}],"responses":{"404":{"description":"Unable to find user","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"204":{"description":"User has been deleted and offboarding has started","content":{"application/scim+json":{}}}}}},"/scim/v2/Users":{"get":{"tags":["People"],"summary":"List users","operationId":"listUsers","parameters":[{"name":"filter","in":"query","description":"Fetch user with a given name or email address using SCIM operators \n\n Examples: \n\n emails.value eq \"test@email.com\" \n\n name.givenName eq \"James\" and name.familyName eq \"Bond\"","schema":{"type":"string"}},{"name":"startIndex","in":"query","description":"The 1-based start index of the first user to be returned","schema":{"type":"integer"}},{"name":"count","in":"query","description":"The number of users to be returned. A maximum of 50 users will be returned in a page.","schema":{"type":"integer"}},{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","schema":{"type":"string"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"List of users","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UsersSchema"}}}}}},"post":{"tags":["People"],"summary":"Create a new user within Firstbase","operationId":"createUser","parameters":[{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","required":false,"schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}},"required":true},"responses":{"404":{"description":"Unable to find organization or package","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Unable to create user due to conflict","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"409":{"summary":"A user with this userName already exists","description":"409","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource already exists","scimType":"uniqueness","status":"409"}}}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"201":{"description":"User has been created","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}}}}}},"/scim/v2/Users/csv":{"post":{"tags":["People"],"summary":"Bulk upsert users from CSV","description":"Parses the CSV file and forwards it as a SCIM Bulk request to create and/or update users.\n\nExpected CSV columns (header row): id, forename, surname, email, secondary_email, package_slug, address_line_1, addressLine2, state/region, city_code, country_code, postal_code, phone_number, send_activation_email, cpf_number.\n\nNotes: \n- id: optional UUID. If present, an update (PUT) is generated; if absent, a create (POST) with a bulkId is generated.\n- package_slug: optional; when present and resolvable it is mapped to a packageId.\n- send_activation_email: true/false/yes/no/null (case-insensitive).\n- File must be uploaded as multipart form-data with field name 'file'.- CPF number is mandatory for Brazilian users.","operationId":"bulkUpsertUsersFromCsv","parameters":[{"name":"file","in":"query","description":"CSV file containing users to upsert. Columns should match the Firstbase CSV template.","required":true,"schema":{"type":"string","format":"binary"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object"},"examples":{"People CSV template":{"summary":"Upload as form-data field 'file'","description":"Example CSV content for the 'file' field.","value":"\n                            id,forename,surname,email,secondary_email,package_slug,address_line_1,addressLine2,state/region,city_code,country_code,postal_code,phone_number,send_activation_email,cpf_number\n                            55907ba0-6ee7-3c6c-00a9-8becwb9k83dk,Name,ExampleSurname,email@example.com,example-optional-secondary-email@email.com,developer-a,Test address line 1,Test address line 2,test state,TN,US,37076,6155555555,YES,87425365821\n                            "}}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Bulk operation completed","content":{"application/scim+json":{"schema":{"type":"string"}}}}}}},"/scim/v2/Bulk":{"post":{"tags":["People"],"summary":"SCIM Bulk operations","description":"Performs bulk operations using the SCIM protocol as defined by RFC 7644.","operationId":"scimBulkOperations","requestBody":{"content":{"application/scim+json":{"schema":{"type":"string"},"examples":{"BulkCreateUpdateUsers":{"summary":"Create a user and update an existing user","description":"SCIM Bulk request that creates a new user and updates an existing one.","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],"failOnErrors":1,"Operations":[{"bulkId":"bulk-test","method":"POST","path":"/Users","data":{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User"],"userName":"testa@example.com","name":{"givenName":"Name","familyName":"ExampleSurname"},"emails":[{"value":"testa@example.com","primary":true},{"value":"testb@email.com","primary":false}],"addresses":[{"type":"home","primary":true,"country":"US","streetAddress":"Test address","postalCode":"37076","region":"test state","locality":"TN"}],"id":"55907ba0-6ee8-4c6c-90a9-8aeccb9b82dc","phoneNumbers":[{"value":"6155555555","primary":true}],"urn:ietf:params:scim:schemas:extension:firstbase:1.0:User":{"packageId":"d41ebe30-279f-41cd-8ag5-7257854d82e5","skipUserActivation":true,"cpfNumber":"87452365895"}}},{"method":"PUT","path":"/Users/4599d8bb-b6df-4ed2-9ad2-6907f8b1fa03","data":{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User"],"userName":"dev+admin@firstbasedev.com","name":{"givenName":"Test Given Name","familyName":"Test familyName"},"emails":[{"value":"test+swaggera@firstbasedev.com","primary":true},{"value":"test+swaggerb@firstbasedev.com","primary":false}],"addresses":[{"type":"home","primary":true,"country":"US","streetAddress":"Test address ","postalCode":"37076","region":"test state","locality":"TN"}],"id":"4599d8bb-b6df-4ed2-9ad2-6907f8b1fa03","phoneNumbers":[{"value":"6155555555","primary":true}],"urn:ietf:params:scim:schemas:extension:firstbase:1.0:User":{"packageId":"d82ebe36-299f-40ce-8af7-7157853d80d9","skipUserActivation":true,"cpfNumber":"87452365895"}}}]}}}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Bulk operation completed","content":{"application/scim+json":{"schema":{"type":"string"}}}}}}},"/api/orders":{"get":{"tags":["Orders"],"summary":"Get all orders","operationId":"getOrders","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":100},"example":10},{"name":"personId","in":"query","description":"The ID of the person to return orders for","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"uuid"},"example":"d7d0d906-425f-402f-bde1-39031c67c40b"},{"name":"startDate","in":"query","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date-time"},"example":"2007-12-03T10:15:30"},{"name":"endDate","in":"query","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date-time"},"example":"2007-12-03T10:15:30"}],"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"post":{"tags":["Orders"],"summary":"Create an order","operationId":"createOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateOrderRequest"}}},"required":true},"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateOrderResponse"}}}}}}},"/api/orders/{orderId}/decline":{"post":{"tags":["Orders - BETA"],"summary":"Decline an order","description":"Transitions an order from AWAITING_APPROVAL to DECLINED status. All non-cancelled order items are also set to DECLINED. Sends a decline notification email for person orders.","operationId":"declineOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Order is not in AWAITING_APPROVAL status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Order declined successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"/api/orders/{orderId}/approve":{"post":{"tags":["Orders - BETA"],"summary":"Approve an order","description":"Transitions an order from AWAITING_APPROVAL to APPROVED status. Optionally accepts an approvedByPersonId to record who approved the order. Sends an approval notification email for person orders.","operationId":"approveOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIApproveOrderRequest"}}}},"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Order is not in AWAITING_APPROVAL status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Order approved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"/api/itad/requests":{"get":{"tags":["ITAD"],"summary":"List ITAD requests","operationId":"listITADRequests","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":25,"maximum":100},"example":25},{"name":"status","in":"query","description":"Filter by request status","required":false,"allowEmptyValue":true,"schema":{"type":"string","enum":["PENDING_DATA_DESTRUCTION","REQUIRES_ACTION","AWAITING_RECHECK","PENDING_SETTLEMENT","COMPLETED","CANCELLED"]}},{"name":"warehouseId","in":"query","description":"Filter by warehouse ID","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"uuid"},"example":"00000000-0000-0000-0000-000000000000"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Paginated list of ITAD requests","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ITADRequest"}}}}}}},"post":{"tags":["ITAD"],"summary":"Create ITAD requests","description":"Create ITAD requests from a list of inventory IDs. Items are automatically grouped by warehouse, creating one request per warehouse.","operationId":"createITADRequests","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateITADRequestsRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request (invalid inventory IDs, ineligible assets, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"201":{"description":"ITAD requests created successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ITADRequest"}}}}}}}},"/api/inventory/{inventoryId}/tags":{"post":{"tags":["Inventory"],"summary":"Add tags to inventory","operationId":"addTagsToInventory","parameters":[{"name":"inventoryId","in":"path","description":"The Inventory ID to add the tags to","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIAddTagsRequest"}}},"required":true},"responses":{"404":{"description":"Inventory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Tag already exists for the inventory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Tags added successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryTag"}}}}}}}},"/api/inventory-orders":{"get":{"tags":["Inventory Orders"],"summary":"List all inventory orders in paginated result","operationId":"listInventoryOrders","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":100},"example":10},{"name":"ids","in":"query","description":"Filter by inventory order IDs","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"statuses","in":"query","description":"Filter by order statuses","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","enum":["CANCELLED","COMPLETE","ORDERED","PARTIALLY_RECEIVED","PROCESSING","RECEIVED","SHIPPED","SUBMITTED"]}}},{"name":"warehouseIds","in":"query","description":"Filter by warehouse IDs","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"categories","in":"query","description":"Filter by product categories","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"brands","in":"query","description":"Filter by product brands","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"customerPoNumbers","in":"query","description":"Filter by customer PO numbers","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the order","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"includeOrdersWithoutSubmitter","in":"query","description":"When true, includes orders without a submitter (system-generated). OR'd with submittedBy if both are provided.","required":false,"allowEmptyValue":true,"schema":{"type":"boolean"}},{"name":"reasons","in":"query","description":"Filter by order reasons","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","enum":["ONE_OFF","RESTOCK"]}}},{"name":"createdDateFrom","in":"query","description":"Filter orders created after this date (ISO-8601). Optional. If provided, createdDateTo must also be provided.","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date"},"example":"2024-01-01"},{"name":"createdDateTo","in":"query","description":"Filter orders created before this date (ISO-8601). Optional. If provided, createdDateFrom must also be provided.","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date"},"example":"2024-12-31"},{"name":"expectedShipDateFrom","in":"query","description":"Filter orders with expected ship date after this date (ISO-8601). Optional. If provided, expectedShipDateTo must also be provided.","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date"},"example":"2024-01-01"},{"name":"expectedShipDateTo","in":"query","description":"Filter orders with expected ship date before this date (ISO-8601). Optional. If provided, expectedShipDateFrom must also be provided.","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date"},"example":"2024-12-31"},{"name":"searchString","in":"query","description":"Search string to filter orders","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"laptop"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"post":{"tags":["Inventory Orders"],"summary":"Create an inventory order","description":"Creates an inventory order to send equipment to a warehouse","operationId":"createInventoryOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryOrderRequest"}}},"required":true},"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"201":{"description":"Inventory order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"/api/inventory/{inventoryId}":{"get":{"tags":["Inventory"],"summary":"Get inventory details","operationId":"getInventory","parameters":[{"name":"inventoryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Inventory fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}}}},"patch":{"tags":["Inventory"],"summary":"Update inventory details","operationId":"updateInventory","parameters":[{"name":"inventoryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Inventory updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}}}}},"/api/shipments":{"get":{"tags":["Shipment - BETA"],"summary":"List all shipments in paginated result","operationId":"listShipments","parameters":[{"name":"trackingNumbers","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":10},"example":10}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaginatedShipmentDetailsDto"}}}}}}}},"/api/returns":{"get":{"tags":["Returns"],"summary":"List all returns","description":"Returns a paginated list of return orders. Each return includes 4 retrieval method types (PL, RETURN_KIT, INBOUND, NOT_MAPPED) with items grouped by method. Empty arrays indicate no items use that method.","operationId":"listReturns","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1,"minimum":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":100,"maximum":500},"example":10},{"name":"personIDs","in":"query","description":"The list of persons that will be returned","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"isReplacement","in":"query","description":"Filter for replacement or return orders without return","required":false,"allowEmptyValue":true,"schema":{"type":"boolean"}},{"name":"includeShipment","in":"query","description":"Include shipment data","required":false,"allowEmptyValue":true,"schema":{"type":"boolean"}},{"name":"startDate","in":"query","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date-time"},"example":"2007-12-03T10:15:30"},{"name":"endDate","in":"query","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date-time"},"example":"2007-12-03T10:15:30"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Paginated list of return orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}}},"/api/returns/{id}":{"get":{"tags":["Returns"],"summary":"Fetch return","operationId":"getReturn","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"includeShipment","in":"query","description":"Include shipment data","required":false,"allowEmptyValue":true,"schema":{"type":"boolean"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}},"/api/packages":{"get":{"tags":["Packages"],"summary":"List all packages","operationId":"listPackages","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":100},"example":10}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Package"}}}}}}}},"/api/orders/{orderId}":{"get":{"tags":["Orders"],"summary":"Get an order by ID","operationId":"getOrderById","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"/api/itad/requests/{requestId}":{"get":{"tags":["ITAD"],"summary":"Get ITAD request details","operationId":"getITADRequest","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"ITAD request details including items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITADRequest"}}}}}}},"/api/itad/eligible-assets":{"get":{"tags":["ITAD"],"summary":"List eligible ITAD assets","description":"List inventory assets eligible for ITAD disposition. Eligibility is based on category, deploy status, and other criteria.","operationId":"listEligibleITADAssets","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":25,"maximum":100},"example":25},{"name":"warehouseId","in":"query","description":"Filter by warehouse ID","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"uuid"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"categoryCode","in":"query","description":"Filter by category code (e.g. COMPUTER, TABLET)","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"COMPUTER"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Paginated list of eligible inventory assets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Inventory"}}}}}}}},"/api/inventory":{"get":{"tags":["Inventory"],"summary":"List all inventory","operationId":"listInventories","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":100},"example":10},{"name":"personId","in":"query","description":"Id of a person to which inventory is assigned","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"warehouseId","in":"query","description":"Id of a warehouse to which inventory is assigned","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"officeId","in":"query","description":"Id of an office to which inventory is assigned","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"categories","in":"query","description":"The code of the categories","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"deployStatuses","in":"query","description":"The deployment statuses","required":false,"schema":{"type":"array","items":{"type":"string","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","GIFTED","LOCKED","ON_HOLD","OUT_FOR_REPAIR","UNAVAILABLE","VOIDED"]}}},{"name":"skuIds","in":"query","description":"Ids of SKU","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"searchString","in":"query","description":"Keyword to search for - This searches the description, the name of the manufacturer, the category, the item's title, and the serial number.","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"Air"},{"name":"updatedAtFrom","in":"query","description":"UTC Date-time to filter inventory updated after (ISO-8601 without timezone)","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date-time"},"example":"2007-12-03T10:15:30"},{"name":"updatedAtTo","in":"query","description":"UTC Date-time to filter inventory updated before (ISO-8601 without timezone)","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"date-time"},"example":"2007-12-03T10:15:30"},{"name":"assignedEmail","in":"query","description":"Email address of the person to which inventory is assigned. Alternative to personId — cannot be combined with personId.","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"employee@company.com"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Inventory"}}}}}}}},"/api/catalog/skus":{"get":{"tags":["Catalog"],"summary":"Get organization's catalog SKUs","operationId":"getOrganizationCatalogSKUs","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32"},"example":10},{"name":"categories","in":"query","description":"The code of the categories","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SimplifiedProductItemDTO"}}}}}}}},"/api/catalog/skus/{skuId}":{"get":{"tags":["Catalog"],"summary":"Get organization's SKU","operationId":"getOrganizationCatalogSKU","parameters":[{"name":"skuId","in":"path","description":"The SKU ID to return data for","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimplifiedProductItemDTO"}}}}}}},"/api/inventory/{inventoryId}/tags/{tagId}":{"delete":{"tags":["Inventory"],"summary":"Remove tag from inventory","operationId":"removeTagFromInventory","parameters":[{"name":"inventoryId","in":"path","description":"The Inventory ID to remove the tag from","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"tagId","in":"path","description":"The Tag ID to remove","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"404":{"description":"Inventory or Tag not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HttpErrors"}}}},"200":{"description":"Tag successfully removed from inventory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryTag"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"detail":{"type":"string","example":"Field \"firstName\" is required"},"source":{"type":"string","example":"person:firstName"}},"required":["detail","source"]},"HttpErrors":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}},"required":["errors"]},"Address":{"type":"object","properties":{"country":{"type":"string","description":"The country name component. The value MUST be in ISO 3166-1 \"alpha-2\" code format.","example":"US"},"locality":{"type":"string","description":"The city or locality component.","example":"New York City"},"postalCode":{"type":"string","description":"The zip code or postal code component.","example":10123},"region":{"type":"string","description":"The state or region component.","example":"NY"},"streetAddress":{"type":"string","description":"The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.  This attribute MAY contain newlines. Only the first 2 lines will be used.","example":123},"primary":{"type":"boolean","description":"When true, the address will be the user's mailing address.","example":true}},"required":["country"]},"Email":{"type":"object","properties":{"value":{"type":"string","example":"jenny.smith@example.com"},"primary":{"type":"boolean","example":true}},"required":["value"]},"FirstbaseUser":{"type":"object","properties":{"packageId":{"type":"string","format":"uuid","example":"d1b0fd87-5fc9-410c-b641-0b7146896ccd"},"startDate":{"type":"string","example":"2022-02-01"},"status":{"type":"string","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"],"example":"ACTIVE"},"skipUserActivation":{"type":"boolean","example":false},"cpfNumber":{"type":"string","example":87456236985}},"required":["skipUserActivation"]},"Name":{"type":"object","properties":{"familyName":{"type":"string","example":"Smith"},"givenName":{"type":"string","example":"Jenny"}},"required":["familyName","givenName"]},"PhoneNumber":{"type":"object","properties":{"value":{"type":"string","example":"1+555-867-5309"},"primary":{"type":"boolean","example":true}},"required":["value"]},"UserSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"addresses":{"type":"array","description":"A physical mailing address for this user. If multiple addresses are present, the element that will be used as the user's Firstbase address will be selected by the following precedence: type `home` marked as `primary`, the first `home` address, the `primary` address, otherwise the first provided address.","items":{"$ref":"#/components/schemas/Address"}},"userName":{"type":"string","description":"The userName must match the `primary` email address.","example":"jenny.smith@example.com"},"emails":{"type":"array","description":"Email addresses for the user. If multiple addresses are present, the `primary` will be used, otherwise the first element will be the user's Firstbase primary email AND userName.","items":{"$ref":"#/components/schemas/Email"}},"name":{"$ref":"#/components/schemas/Name","description":"The components of the user's name."},"phoneNumbers":{"type":"array","description":"Phone numbers for the user. The value SHOULD be specified according to the format defined in [RFC3966], e.g., 'tel:+1-201-555-0123' If multiple phone numbers are present, the `primary` otherwise the first element will be the user's Firstbase phone number.","items":{"$ref":"#/components/schemas/PhoneNumber"}},"urn:ietf:params:scim:schemas:extension:firstbase:1.0:User":{"$ref":"#/components/schemas/FirstbaseUser","description":"Define attributes of the User's on-boarding, including their initial package ID and start date."},"schemas":{"type":"array","description":"The schemas defining the attributes of the resources.","example":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User"],"items":{"type":"string"}}},"required":["addresses","emails","id","name","schemas","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User","userName"]},"ErrorSchema":{"type":"object","properties":{"schemas":{"type":"array","items":{"type":"string"}},"detail":{"type":"string"},"scimType":{"type":"string"},"status":{"type":"string"}},"required":["detail","schemas","status"]},"PublicAPICreateOrderResponse":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"itemIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["itemIds","orderId"]},"PublicAPICreateOrderRequest":{"type":"object","description":"Request body for creating a new order. Either `personId` or `officeId` must be provided, but not both.","properties":{"shippingAddress":{"$ref":"#/components/schemas/PublicAPICreateShippingAddress","description":"The shipping address for the order."},"personId":{"type":"string","format":"uuid","description":"The ID of the person receiving the order. Either this or `officeId` must be set, but not both.","example":"123e4567-e89b-12d3-a456-426614174000"},"officeId":{"type":"string","format":"uuid","description":"The ID of the office receiving the order. Either this or `personId` must be set, but not both.","example":"123e4567-e89b-12d3-a456-426614174001"},"skus":{"type":"array","description":"A list of SKUs (items) to include in the order.","items":{"$ref":"#/components/schemas/PublicAPISkuInformation"}}},"required":["shippingAddress","skus"]},"PublicAPICreateShippingAddress":{"type":"object","description":"Shipping address","properties":{"addressLine1":{"type":"string","description":"The primary line of the address (e.g., house number and street name)","example":123},"addressLine2":{"type":"string","description":"Additional address information (e.g., apartment or suite number)","example":"Apartment B"},"administrativeArea":{"type":"string","description":"The state, province, or region within the country","example":"California"},"countryCode":{"type":"string","description":"A two-letter ISO 3166-1 alpha-2 code representing the country","example":"US"},"dependentLocality":{"type":"string","description":"A smaller subdivision within the locality, often used for neighborhoods or districts","example":"Mission Bay"},"locality":{"type":"string","description":"The city or town within the administrative area","example":"San Francisco"},"postalCode":{"type":"string","description":"The ZIP code or equivalent postal code","example":94158},"sortingCode":{"type":"string","description":"A code used for routing or sorting mail, often specific to postal systems.","example":"94158-1234"},"phoneNumber":{"type":"string","description":"A contact phone number, including the international dialing code","example":"+1-415-555-1234"}},"required":["countryCode"]},"PublicAPISkuInformation":{"type":"object","description":"SKU information","properties":{"id":{"type":"string","format":"uuid"},"expeditedShippingOption":{"type":"string","description":"Expedited Shipping","enum":["EXPEDITED_STANDARD"]},"preferredCondition":{"type":"string","enum":["NEW","USED"]}},"required":["id"]},"AddressInfo":{"type":"object","properties":{"addressLine1":{"type":"string","example":123},"addressLine2":{"type":"string","example":"Suite 103"},"administrativeArea":{"type":"string","description":"the state or county","example":"NY"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"US"},"locality":{"type":"string","description":"the city","example":"New York City"},"postalCode":{"type":"string","description":"the postal code or zip code","example":10123}},"required":["countryCode"]},"PublicAPIGetOrderResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Order's ID","example":"123E4567-E89B-12D3-A456-426614174000"},"personId":{"type":"string","format":"uuid","description":"The ID of the Person","example":"d7d0d906-425f-402f-bde1-39031c67c40b"},"officeId":{"type":"string","format":"uuid","description":"The ID of the Office","example":"d7d0d906-425f-402f-bde1-39031c67c40b"},"status":{"type":"string","description":"Order's status","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"COMPLETED"},"orderItems":{"type":"array","description":"Order items details","items":{"$ref":"#/components/schemas/PublicAPIOrderItemResponse"}},"statusHistory":{"type":"array","description":"Chronological history of status changes","items":{"$ref":"#/components/schemas/StatusHistoryEntry"}},"shippingAddress":{"$ref":"#/components/schemas/AddressInfo","description":"Order item's shipping address"},"orderType":{"type":"string","description":"Type of order based on lifecycle context","enum":["ONE_OFF","ONBOARDING","REPLACEMENT"]},"submittedBy":{"type":"string","description":"Name of the person who submitted the order","example":"John S. (Firstbase)"},"approvedBy":{"type":"string","description":"Name of the person who approved the order","example":"Jane Smith"},"approvedAt":{"type":"string","format":"date","description":"Date when the order was approved","example":"2026-02-26"}},"required":["id","orderItems","orderType","shippingAddress","status","statusHistory"]},"PublicAPIOrderItemResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Order item's ID","example":"123E4567-E89B-12D3-A456-426614174000"},"skuId":{"type":"string","format":"uuid","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"},"title":{"type":"string","description":"Product title","example":"iPad Air - Silver, 64GB, WiFi"},"categoryCode":{"type":"string","description":"Product category code","example":"COMPUTER"},"status":{"type":"string","description":"Order item's status","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"PROCESSING"},"shipment":{"$ref":"#/components/schemas/PublicAPIOrderItemShipmentResponse","description":"Order item's shipment details"},"statusHistory":{"type":"array","description":"Chronological history of status changes","items":{"$ref":"#/components/schemas/StatusHistoryEntry"}},"fulfillmentMethod":{"type":"string","description":"Order item's fulfillment method","enum":["WAREHOUSE","DROPSHIP"]}},"required":["categoryCode","id","skuId","status","statusHistory","title"]},"PublicAPIOrderItemShipmentResponse":{"type":"object","properties":{"trackingUrl":{"type":"string"},"trackingCode":{"type":"string","description":"Tracking code","example":"1Z00000000"},"carrier":{"type":"string","description":"The carrier name","example":"UPS"},"status":{"type":"string","description":"The current status of the shipment","example":"DELIVERED"},"trackingHistory":{"type":"array","description":"A history of recorded shipment status updates in order of date received","items":{"$ref":"#/components/schemas/PublicAPIOrderItemShipmentStatusDTO"}}}},"PublicAPIOrderItemShipmentStatusDTO":{"type":"object","properties":{"status":{"type":"string","description":"The status of the shipment","example":"IN_TRANSIT"},"timestamp":{"type":"string","format":"date-time","description":"Timestamp at which the event was received"}},"required":["status","timestamp"]},"StatusHistoryEntry":{"type":"object","properties":{"status":{"type":"string","description":"Order status at time of change","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"APPROVED"},"timestamp":{"type":"string","format":"date-time","description":"Timestamp of status change in UTC","example":"2023-01-01T12:00:00Z"}},"required":["status","timestamp"]},"PublicAPIApproveOrderRequest":{"type":"object","properties":{"approvedByPersonId":{"type":"string","format":"uuid","description":"Optional person ID to record as the approver","example":"d7d0d906-425f-402f-bde1-39031c67c40b"}}},"ITADRequest":{"type":"object","description":"An ITAD (IT Asset Disposition) request","properties":{"id":{"type":"string","format":"uuid","description":"Unique request ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","description":"Current request status","enum":["PENDING_DATA_DESTRUCTION","REQUIRES_ACTION","AWAITING_RECHECK","PENDING_SETTLEMENT","COMPLETED","CANCELLED"],"example":"PENDING_DATA_DESTRUCTION"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the request was created"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when the request was completed"},"cancelledAt":{"type":"string","format":"date-time","description":"Timestamp when the request was cancelled"},"totalEstimatedResaleValue":{"type":"number","description":"Total estimated resale value of all items","example":2500.0},"totalResaleValue":{"type":"number","description":"Total actual resale value of all items","example":2300.0},"submittedVia":{"type":"string","description":"How the request was submitted","enum":["ASSETS_PAGE","ITAD_CENTER","RETURN"],"example":"ITAD_CENTER"},"createdByActor":{"type":"string","description":"Actor who created the request","enum":["CUSTOMER","OPS"],"example":"CUSTOMER"},"warehouseId":{"type":"string","format":"uuid","description":"ID of the warehouse","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"warehouseName":{"type":"string","description":"Name of the warehouse","example":"US East Warehouse"},"organizationId":{"type":"string","format":"uuid","description":"ID of the organization","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"organizationName":{"type":"string","description":"Name of the organization","example":"Acme Corp"},"createdById":{"type":"string","format":"uuid","description":"ID of the person who created the request","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"createdByName":{"type":"string","description":"Name of the person who created the request","example":"John Doe"},"lotCodDocumentId":{"type":"string","format":"uuid","description":"Lot Certificate of Destruction document ID"},"lotCodUploadedAt":{"type":"string","format":"date-time","description":"Timestamp when the lot CoD was uploaded"},"settlementReportDocumentId":{"type":"string","format":"uuid","description":"Settlement report document ID"},"settlementReportGeneratedAt":{"type":"string","format":"date-time","description":"Timestamp when the settlement report was generated"},"parentItadRequestId":{"type":"string","format":"uuid","description":"Parent ITAD request ID for multi-warehouse bulk submissions"},"items":{"type":"array","description":"Items in this request (included in detail responses only)","items":{"$ref":"#/components/schemas/ITADRequestItem"}}},"required":["createdByActor","id","status","submittedVia"]},"ITADRequestItem":{"type":"object","description":"An item within an ITAD request","properties":{"id":{"type":"string","format":"uuid","description":"Unique item ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"inventoryId":{"type":"string","format":"uuid","description":"ID of the inventory asset","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"serialNumber":{"type":"string","description":"Serial number of the asset","example":"C02X1234ABCD"},"skuTitle":{"type":"string","description":"Product title of the SKU","example":"MacBook Pro 14\" M2"},"categoryCode":{"type":"string","description":"Category code of the SKU","example":"COMPUTER"},"estimatedResaleValue":{"type":"number","description":"Estimated resale value","example":450.0},"resaleValue":{"type":"number","description":"Actual resale value","example":420.0},"estimatedMaxCreditValueAtRequest":{"type":"number","description":"Estimated max credit value at time of request","example":500.0},"rmsStatus":{"type":"string","description":"RMS enrollment status","enum":["NOT_ENROLLED","UNENROLLMENT_REQUIRED","AWAITING_RECHECK","CLEARED"],"example":"NOT_ENROLLED"},"status":{"type":"string","description":"Item status","enum":["PENDING","ENQUEUED","DATA_DESTRUCTION_COMPLETED","SETTLED","CANCELLED"],"example":"PENDING"},"settledAmount":{"type":"number","description":"Settled amount after disposition","example":400.0},"grossSaleAmount":{"type":"number","description":"Gross sale amount","example":410.0},"currencyCode":{"type":"string","description":"Currency code for monetary values","example":"USD"},"cancelledAt":{"type":"string","format":"date-time","description":"Timestamp when the item was cancelled"}},"required":["id"]},"CreateITADRequestsRequest":{"type":"object","description":"Request body to create ITAD requests","properties":{"inventoryIds":{"type":"array","description":"List of inventory IDs to include in the ITAD request(s). Items will be grouped by warehouse.","items":{"type":"string","format":"uuid"},"minItems":1},"createdById":{"type":"string","format":"uuid","description":"ID of the person creating the request (must belong to the organization)","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"}},"required":["createdById","inventoryIds"]},"InventoryTag":{"type":"object","description":"A tag associated to an inventory","properties":{"id":{"type":"string","format":"uuid","example":"8e0caa73-cc71-4aa4-88eb-fca494de8e20"},"label":{"type":"string","example":"Engineering"}},"required":["id","label"]},"PublicAPIAddTagsRequest":{"type":"object","description":"Request body","properties":{"labels":{"type":"array","description":"Set of labels to be added as tags","examples":["Tag 1","Tag 2"],"items":{"type":"string"},"uniqueItems":true}},"required":["labels"]},"InventoryOrderInventoryResponse":{"type":"object","description":"Inventory information for a shipment item","properties":{"id":{"type":"string","format":"uuid","description":"Inventory ID","example":"123E4567-E89B-12D3-A456-426614174000"},"serialNumber":{"type":"string","description":"Serial number","example":"SN123456789"},"deployStatus":{"type":"string","description":"Deploy status","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","GIFTED","LOCKED","ON_HOLD","OUT_FOR_REPAIR","UNAVAILABLE","VOIDED"],"example":"DEPLOYED"},"warehouse":{"$ref":"#/components/schemas/WarehouseInfo","description":"Warehouse name","example":"Main Warehouse"}},"required":["deployStatus","id"]},"InventoryOrderItemReference":{"type":"object","description":"Reference to inventory order item","properties":{"id":{"type":"string","format":"uuid","description":"Inventory order item ID","example":"123E4567-E89B-12D3-A456-426614174000"}},"required":["id"]},"InventoryOrderItemResponse":{"type":"object","description":"Inventory order item information","properties":{"id":{"type":"string","format":"uuid","description":"Order item ID","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"Order item status","enum":["ACTIVATED","ARRIVED_AT_PROCESSING_FACILITY","CANCELLED","DELIVERY_EXCEPTION","ORDERED","OUT_FOR_DELIVERY","PARTIALLY_ACTIVATED","PARTIALLY_RECEIVED","PARTIALLY_SHIPPED","PENDING","RECEIVED","SHIPPED"],"example":"RECEIVED"},"sku":{"$ref":"#/components/schemas/SkuReference","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"},"pricing":{"$ref":"#/components/schemas/PricingInfo","description":"Pricing information"},"quantity":{"type":"integer","format":"int32","description":"Quantity","example":2},"discountedPrice":{"type":"number","description":"Discounted price","example":999.0},"warranty":{"description":"Warranty item if this is a physical item with warranty","required":["id","pricing","quantity","sku","status"]},"type":{"type":"string","description":"Item type","enum":["PHYSICAL","SERVICE"],"example":"PHYSICAL"},"expectedShipDate":{"type":"string","format":"date","description":"Expected ship date","example":"2026-01-20"}},"required":["id","pricing","quantity","sku","status","type"]},"InventoryOrderResponse":{"type":"object","description":"Inventory order information","properties":{"id":{"type":"string","format":"uuid","description":"Order ID","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"Order status","enum":["CANCELLED","COMPLETE","ORDERED","PARTIALLY_RECEIVED","PROCESSING","RECEIVED","SHIPPED","SUBMITTED"],"example":"PROCESSING"},"warehouse":{"$ref":"#/components/schemas/WarehouseReference","description":"Warehouse information"},"customerPoNumber":{"type":"string","description":"Customer PO number","example":"PO-12345"},"reason":{"type":"string","description":"Order reason","enum":["ONE_OFF","RESTOCK"],"example":"ONE_OFF"},"billingType":{"type":"string","description":"Billing type","enum":["SUBSCRIPTION","PURCHASED"],"example":"SUBSCRIPTION"},"submittedBy":{"$ref":"#/components/schemas/PersonReference","description":"Person who submitted the order"},"inventoryOrderItems":{"type":"array","description":"Inventory order items","items":{"$ref":"#/components/schemas/InventoryOrderItemResponse"}},"inventoryOrderShipments":{"type":"array","description":"Inventory order shipments","items":{"$ref":"#/components/schemas/InventoryOrderShipmentResponse"}}},"required":["id","inventoryOrderItems","inventoryOrderShipments","reason","status","warehouse"]},"InventoryOrderShipmentItemResponse":{"type":"object","description":"Shipment item information","properties":{"id":{"type":"string","format":"uuid","description":"Shipment item ID","example":"123E4567-E89B-12D3-A456-426614174000"},"inventoryOrderItem":{"$ref":"#/components/schemas/InventoryOrderItemReference","description":"Inventory order item ID","example":"123E4567-E89B-12D3-A456-426614174000"},"quantity":{"type":"integer","format":"int32","description":"Quantity","example":2},"status":{"type":"string","description":"Shipment item status","enum":["ARRIVED_AT_PROCESSING_FACILITY","CANCELLED","DELIVERY_EXCEPTION","ORDERED","OUT_FOR_DELIVERY","RECEIVED","SHIPPED"],"example":"RECEIVED"},"inventories":{"type":"array","description":"Inventories associated with this shipment item","items":{"$ref":"#/components/schemas/InventoryOrderInventoryResponse"}}},"required":["id","inventories","inventoryOrderItem","quantity","status"]},"InventoryOrderShipmentResponse":{"type":"object","description":"Shipment information for an inventory order","properties":{"id":{"type":"string","format":"uuid","description":"Shipment ID","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"Shipment status","enum":["ARRIVED_AT_PROCESSING_FACILITY","CANCELLED","DELIVERY_EXCEPTION","OUT_FOR_DELIVERY","PARTIALLY_RECEIVED","PENDING","RECEIVED","SHIPPED"],"example":"SHIPPED"},"shippingCarrier":{"type":"string","description":"Shipping carrier","example":"UPS"},"trackingCode":{"type":"string","description":"Tracking code","example":"1Z00000000"},"trackingUrl":{"type":"string","description":"Tracking URL","example":"https://tracking.example.com/1Z00000000"},"trackingStatus":{"type":"string","description":"Tracking status","enum":["DELIVERED","EXCEPTION","IN_TRANSIT","OUT_FOR_DELIVERY","PRE_TRANSIT"],"example":"IN_TRANSIT"},"trackingShipmentId":{"type":"string","format":"uuid","description":"Tracking shipment ID","example":"123E4567-E89B-12D3-A456-426614174000"},"estimatedDeliveryDate":{"type":"string","format":"date","description":"Estimated delivery date","example":"2024-01-15"},"etaStart":{"type":"string","format":"date","description":"Estimated delivery start date from tracking provider","example":"2024-01-14"},"etaEnd":{"type":"string","format":"date","description":"Estimated delivery end date from tracking provider","example":"2024-01-16"},"inventoryOrderShipmentItems":{"type":"array","description":"Shipment items","items":{"$ref":"#/components/schemas/InventoryOrderShipmentItemResponse"}}},"required":["id","inventoryOrderShipmentItems","status"]},"PersonReference":{"type":"object","description":"Reference to person","properties":{"id":{"type":"string","format":"uuid","description":"Person ID","example":"123E4567-E89B-12D3-A456-426614174000"}},"required":["id"]},"PricingInfo":{"type":"object","description":"Pricing information for an inventory order item","properties":{"id":{"type":"string","format":"uuid","description":"Pricing ID","example":"123E4567-E89B-12D3-A456-426614174000"},"price":{"type":"integer","format":"int64","description":"Price in cents","example":99900}}},"SkuReference":{"type":"object","description":"Reference to SKU","properties":{"id":{"type":"string","format":"uuid","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"}},"required":["id"]},"WarehouseInfo":{"type":"object","description":"Warehouse information","properties":{"name":{"type":"string","description":"Warehouse name","example":"Main Warehouse"}},"required":["name"]},"WarehouseReference":{"type":"object","description":"Reference to warehouse","properties":{"id":{"type":"string","format":"uuid","description":"Warehouse ID","example":"123E4567-E89B-12D3-A456-426614174000"}},"required":["id"]},"CreateInventoryOrderItemRequest":{"type":"object","description":"An item to include in an inventory order","properties":{"skuId":{"type":"string","format":"uuid","description":"SKU ID of the product to order"},"quantity":{"type":"integer","format":"int32","description":"Quantity to order","example":1,"minimum":1}},"required":["quantity","skuId"]},"CreateInventoryOrderRequest":{"type":"object","description":"Request to create an inventory order","properties":{"warehouseId":{"type":"string","format":"uuid","description":"Warehouse ID where the inventory will be sent"},"regionId":{"type":"string","format":"uuid","description":"Region ID. Required when the organization uses multi-entity"},"items":{"type":"array","description":"Items to include in the inventory order","items":{"$ref":"#/components/schemas/CreateInventoryOrderItemRequest"},"maxItems":100,"minItems":0},"billingType":{"type":"string","description":"Billing type. Required for HAAS organizations (SUBSCRIPTION or PURCHASED). Non-HAAS organizations default to PURCHASED and cannot use SUBSCRIPTION","enum":["SUBSCRIPTION","PURCHASED"]},"firstbaseSupplied":{"type":"boolean","description":"Whether Firstbase supplies the equipment. Defaults to true","example":true},"trackingNumber":{"type":"string","description":"Tracking number for the shipment","maxLength":255,"minLength":0},"notes":{"type":"string","description":"Additional notes for the order","maxLength":1000,"minLength":0},"expectedShipDate":{"type":"string","format":"date","description":"Expected ship date (ISO-8601)","example":"2026-04-01"},"customerPoNumber":{"type":"string","description":"Customer PO number","maxLength":255,"minLength":0}},"required":["items","warehouseId"]},"InboundRetrievalInfo":{"allOf":[{"$ref":"#/components/schemas/RetrievalMethodInfo"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]},"inboundTrackingCode":{"type":"string"},"inboundTrackingLink":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}}],"description":"INBOUND_LABEL retrieval type information","required":["id"]},"Inventory":{"type":"object","description":"A piece of inventory","properties":{"id":{"type":"string","format":"uuid","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"skuId":{"type":"string","format":"uuid","example":"203a5df2-423a-43a9-bb19-1ccaf3434b91"},"serialNumber":{"type":"string","example":"25f2e6ea9a"},"deployStatus":{"type":"string","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","ON_HOLD","UNAVAILABLE"],"example":"ARCHIVED"},"deployReason":{"type":"string","enum":["ASSIGNED_TO_ADMIN","AWAITING_INFORMATION","BOUGHT_OUT","DATA_HOLD","DECOMMISSIONED_BY_EMPLOYER","END_OF_USEFUL_LIFE_DESTROYED","END_OF_USEFUL_LIFE_DONATED","PENDING_FULFILLMENT","GIFTED_BY_EMPLOYER","GIFTED_BY_FIRSTBASE","IN_TRANSIT","LOCKED_APPLE_ACTIVATION","LOCKED_FMD_REPORTED_LOST_STOLEN","LOCKED_MDM","LOCKED_PIN","LOST_BY_FIRSTBASE","LOST_IN_TRANSIT","LOST_BY_WORKER","MARKED_FOR_DESTRUCTION","NA","NEVER_RECEIVED_BY_WORKER","OTHER","OUT_FOR_DESTRUCTION","OUT_FOR_REPAIR","PENDING_BUY_OUT","RECYCLING_REQUESTED","REQUIRES_CLEANING","REQUIRES_REPAIR","RETURN_IN_PROGRESS","SENT_TO_OFFICE","STOLEN","UNRESPONSIVE_WORKER","UNSUPPORTED_REGION","PERSONAL_DEVICE"],"example":"LOST_BY_WORKER"},"condition":{"type":"string","enum":["NEW","USED_LIKE_NEW","USED_GOOD","USED_FAIR","USED","USED_POOR","UNUSABLE"],"example":"NEW"},"categoryCode":{"type":"string","example":"TSHIRT"},"categoryNameOfSku":{"type":"string","example":"T-shirt"},"skuTitle":{"type":"string","example":"T-shirt White - 5XL"},"vendorCode":{"type":"string","example":"AWESOME_MERCHANDISE"},"vendorSku":{"type":"string","example":"TSHRT_5XL_WHITE"},"createdAt":{"type":"string","format":"date-time","example":"2023-02-09T00:00:00"},"updatedAt":{"type":"string","format":"date-time","example":"2023-03-02T17:39:01.650027"},"renewalDate":{"type":"string","format":"date","example":"2026-02-09"},"renewalDateUpdatedBy":{"type":"string","enum":["RENEWAL_DATE_ORGANIZATION_LEVEL","RENEWAL_DATE_ORGANIZATION_CATEGORY_LEVEL","RENEWAL_DATE_MANUALLY_UPDATED","CLEAR_RENEWAL_DATE_MANUALLY_SET"],"example":"RENEWAL_DATE_ORGANIZATION_LEVEL"},"billingStartDate":{"type":"string","format":"date","example":"2026-02-09"},"billingEndDate":{"type":"string","format":"date","example":"2028-02-09"},"procurementMethod":{"type":"string","example":"Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c"},"returnOrder":{"$ref":"#/components/schemas/InventoryReturnInfo"},"assignedTo":{"$ref":"#/components/schemas/InventoryAssignedToInfo"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/InventoryTag"},"uniqueItems":true},"pricing":{"$ref":"#/components/schemas/SimplifiedProductPriceDTO","description":"Pricing details"},"description":{"type":"string","description":"Custom description for the inventory item","example":"Custom inventory description"}},"required":["categoryCode","categoryNameOfSku","condition","createdAt","deployStatus","id","skuId","skuTitle","tags","updatedAt","vendorCode","vendorSku"]},"InventoryAssignedToInfo":{"type":"object","description":"Information about the inventory assignment","properties":{"id":{"type":"string","format":"uuid","description":"The assigned object's id","example":"371da231-5878-45b1-80a3-9113f8795c29"},"type":{"type":"string","description":"The assigned object's type","enum":["PERSON","WAREHOUSE","OFFICE"],"example":"PERSON"},"label":{"type":"string","description":"The assigned person's email, or the assigned warehouse's name, or the assigned office's name","example":"San Francisco's office"},"assignedAt":{"type":"string","format":"date-time","description":"When was this object assigned"}},"required":["id","label","type"]},"InventoryReturnInfo":{"type":"object","description":"A collection of return related information","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"]},"createdAt":{"type":"string","format":"date-time"},"returnOrderItemId":{"type":"string","format":"uuid"},"returnOrderItemStatus":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"]},"retrievalMethod":{"oneOf":[{"$ref":"#/components/schemas/InboundRetrievalInfo"},{"$ref":"#/components/schemas/PhysicalRetrievalInfo"},{"$ref":"#/components/schemas/ReturnKitRetrievalInfo"}]}}},"PhysicalRetrievalInfo":{"allOf":[{"$ref":"#/components/schemas/RetrievalMethodInfo"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]},"updatedAt":{"type":"string","format":"date-time"}}}],"description":"PHYSICAL retrieval type information","required":["id"]},"RetrievalMethodInfo":{"description":"Retrieval type information","discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"ReturnKitRetrievalInfo":{"allOf":[{"$ref":"#/components/schemas/RetrievalMethodInfo"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]},"inboundTrackingCode":{"type":"string"},"inboundTrackingLink":{"type":"string"},"outboundTrackingCode":{"type":"string"},"outboundTrackingLink":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}}],"description":"RETURN_KIT retrieval type information","required":["id"]},"SimplifiedProductPriceDTO":{"type":"object","properties":{"regionCode":{"type":"string"},"priceOption":{"type":"string"},"price":{"type":"number"},"currencyCode":{"type":"string"},"discountedPrice":{"type":"number"},"discountPercentage":{"type":"number"}},"required":["currencyCode","discountPercentage","discountedPrice","price","priceOption","regionCode"]},"Assignee":{"type":"object","description":"Update the assignment of the inventory","properties":{"id":{"type":"string","format":"uuid","description":"The ID of the person/office to assign the item to","example":"00000000-0000-0000-0000-000000000000"},"type":{"type":"string","description":"Type of assignee","enum":["PERSON","OFFICE"],"example":"OFFICE"}},"required":["id","type"]},"UpdateInventoryRequest":{"type":"object","description":"Request body for updating inventory details","properties":{"deployStatus":{"type":"string","description":" \n            Allowed values:\n            - `UNAVAILABLE`, only applies to inventory assigned to an office.\n            - `AVAILABLE`, only applies to inventory assigned to an office.\n            - `DEPLOYED`, only applies to inventory assigned to a person.\n            - `ARCHIVED`, applies to inventory assigned to a person or an office.\n        ","enum":["ARCHIVED","DEPLOYED","UNAVAILABLE","AVAILABLE"],"example":"ARCHIVED"},"deployReason":{"type":"string","description":"\n            Reason for the deployment change. \n            Allowed values vary based on `deployStatus`:\n            - For `UNAVAILABLE`, valid reasons are [AWAITING_INFORMATION, DATA_HOLD, LOCKED_APPLE_ACTIVATION, LOCKED_FMD_REPORTED_LOST_STOLEN, LOCKED_MDM, LOCKED_PIN, REQUIRES_REPAIR, OUT_FOR_REPAIR].\n            - For `ARCHIVED`, valid reasons are [GIFTED_BY_EMPLOYER, LOST_BY_WORKER, BOUGHT_OUT, PERSONAL_DEVICE, END_OF_USEFUL_LIFE_DESTROYED, END_OF_USEFUL_LIFE_DONATED, DECOMMISSIONED_BY_EMPLOYER].\n            - For `AVAILABLE`, reason must be null.\n            - For `DEPLOYED`, reason must be null.\n        ","enum":["GIFTED_BY_EMPLOYER","LOST_BY_WORKER","BOUGHT_OUT","PERSONAL_DEVICE","END_OF_USEFUL_LIFE_DESTROYED","END_OF_USEFUL_LIFE_DONATED","DECOMMISSIONED_BY_EMPLOYER","AWAITING_INFORMATION","DATA_HOLD","LOCKED_APPLE_ACTIVATION","LOCKED_FMD_REPORTED_LOST_STOLEN","LOCKED_MDM","LOCKED_PIN","REQUIRES_REPAIR","OUT_FOR_REPAIR"],"example":"GIFTED_BY_EMPLOYER"},"assignedTo":{"$ref":"#/components/schemas/Assignee"},"condition":{"type":"string","description":"Condition of the inventory item.","enum":["NEW","USED"],"example":"NEW"}}},"UsersSchema":{"type":"object","properties":{"totalResults":{"type":"integer","format":"int64","description":"The total number of users available","example":102},"itemsPerPage":{"type":"integer","format":"int32","description":"The number of users in the returned page","example":1},"startIndex":{"type":"integer","format":"int32","description":"The 1-based index of the first user in the returned page","example":1},"Resources":{"type":"array","description":"A page of users","items":{"$ref":"#/components/schemas/UserSchema"}},"schemas":{"type":"array","description":"The schemas defining the attributes of the user resources list.","example":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"items":{"type":"string"}}},"required":["Resources","itemsPerPage","schemas","startIndex","totalResults"]},"PaginatedShipmentDetailsDto":{"type":"object","properties":{"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"pageNumber":{"type":"integer","format":"int32"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentOrderItemDto"}}},"required":["data","pageNumber","size","totalElements","totalPages"]},"ShipmentOrderItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Shipment ID","example":"123E4567-E89B-12D3-A456-426614174000"},"trackingCode":{"type":"string","description":"Tracking code","example":"1Z00000000"},"carrier":{"type":"string","description":"The carrier name","example":"UPS"},"status":{"type":"string","description":"The current status of the shipment","example":"DELIVERED"},"trackingHistory":{"type":"array","description":"A history of recorded shipment status updates in order of date received","items":{"$ref":"#/components/schemas/ShipmentStatusDTO"}},"createdAt":{"type":"string","format":"date-time","description":"Timestamp at which the record was created"},"orderItemIds":{"type":"array","description":"A list of associated Order item IDs","examples":["123E4567-E89B-12D3-A456-426614174000","123E4567-E89B-12D3-A456-426614175000"],"items":{"type":"string","format":"uuid"}},"trackingUrl":{"type":"string","description":"Tracking link","example":"http://trackinglink.com/trackingcode"}},"required":["carrier","createdAt","id","status","trackingCode","trackingHistory"]},"ShipmentStatusDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal id of the tracker status","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"The status of the shipment","example":"IN_TRANSIT"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp at which the event was received"}},"required":["createdAt","id","status"]},"ReplacementInfo":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"},"createdAt":{"type":"string","format":"date"},"status":{"type":"string","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"]}},"required":["createdAt","id","status"]},"ReturnOrderInfo":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Return order ID","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"personId":{"type":"string","format":"uuid","description":"Person ID","example":"016fb454-066b-4ba5-9eca-a2fa14b7e7fc"},"supportTicketId":{"type":"integer","format":"int64","description":"Support ticket ID","example":12345},"createdAt":{"type":"string","format":"date","description":"Created date","example":"2025-11-26"},"updatedAt":{"type":"string","format":"date","description":"Updated date","example":"2025-11-26"},"shippingAddress":{"$ref":"#/components/schemas/AddressInfo","description":"Shipping address"},"status":{"type":"string","description":"Return order status","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"],"example":"CONFIRMED"},"retrievals":{"type":"array","description":"Retrieval methods grouped by type. Always contains 4 entries: PL, RETURN_KIT, INBOUND, NOT_MAPPED","items":{"$ref":"#/components/schemas/ReturnRetrievalMethodInfo"}},"replacement":{"$ref":"#/components/schemas/ReplacementInfo","description":"Replacement order if applicable"},"returnLifecycleType":{"type":"string","description":"Return lifecycle type","enum":["ONE_OFF","OFFBOARDING"],"example":"ONE_OFF"}},"required":["id","personId","retrievals"]},"ReturnOrderItemInfo":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Return order item's ID","example":"123E4567-E89B-12D3-A456-426614174000"},"skuId":{"type":"string","format":"uuid","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"},"title":{"type":"string","description":"Product title","example":"iPad Air - Silver, 64GB, WiFi"},"categoryCode":{"type":"string","description":"Product category code","example":"COMPUTER"},"status":{"type":"string","description":"Order item's status","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"PROCESSING"},"shipment":{"$ref":"#/components/schemas/PublicAPIOrderItemShipmentResponse","description":"Order item's shipment details"},"returnReason":{"type":"string","description":"Order item's return reason","enum":["OFFBOARDING","UNKNOWN","OFF_CYCLE","DAMAGED","UPGRADE","STANDARD_LIFECYCLE","PRODUCT_CHANGE","OTHER","LOST_BY_WORKER","LOST_BY_PARTNER","FULFILLMENT_ERROR"]},"inventoryId":{"type":"string","format":"uuid","description":"Order item's inventory id"},"retrievalMethodStatus":{"type":"string","description":"Retrieval method status","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"],"example":"DELIVERED"},"inboundTrackingLink":{"type":"string","description":"Inbound tracking link for return kit","example":"https://tracking.example.com/123456"},"inboundCarrier":{"type":"string","description":"Inbound carrier for return kit","example":"UPS"},"inboundTrackingCode":{"type":"string","description":"Inbound tracking code for return kit","example":"1Z999AA10123456784"},"outboundTrackingLink":{"type":"string","description":"Outbound tracking link for return kit","example":"https://tracking.example.com/789012"},"outboundCarrier":{"type":"string","description":"Outbound carrier for return kit","example":"FedEx"},"outboundTrackingCode":{"type":"string","description":"Outbound tracking code for return kit","example":"1Z999AA10567890123"},"itad":{"type":"boolean","description":"Whether this item was elected for ITAD (IT Asset Disposition)","example":false}},"required":["categoryCode","id","itad","skuId","status","title"]},"ReturnRetrievalMethodInfo":{"type":"object","description":"Retrieval method with associated return items","properties":{"methodType":{"type":"string","description":"Type of retrieval method","enum":["PL","RETURN_KIT","INBOUND","NOT_MAPPED"],"example":"RETURN_KIT"},"items":{"type":"array","description":"List of return items using this retrieval method. Empty array if no items use this method.","items":{"$ref":"#/components/schemas/ReturnOrderItemInfo"}}},"required":["items","methodType"]},"Package":{"type":"object","description":"A package that is assignable to a person","properties":{"id":{"type":"string","format":"uuid","example":"3a68a467-8733-4c8d-a942-16ed7ec33018"},"name":{"type":"string","example":"The works"},"automaticOrder":{"type":"boolean","example":false},"approvalRequired":{"type":"boolean","example":false},"active":{"type":"boolean","example":true},"skuIds":{"type":"array","items":{"type":"string","format":"uuid"}},"assignedTo":{"$ref":"#/components/schemas/PackageAssignedToInformation"}},"required":["active","approvalRequired","assignedTo","automaticOrder","id","name"]},"PackageAssignedToInformation":{"type":"object","properties":{"people":{"type":"array","items":{"type":"string","format":"uuid"}}}},"AvailabilityDTO":{"type":"object","properties":{"condition":{"type":"string","description":"The condition of the item","example":"NEW or USED"},"count":{"type":"integer","format":"int32","description":"The number of available items in this condition","example":1}},"required":["condition","count"]},"ProductPriceDetails":{"type":"object","properties":{"regionCode":{"type":"string","description":"Region where this product is available","example":"EU"},"priceOption":{"type":"string","description":"The billing type","example":"Subscription or Purchased"},"price":{"type":"number","description":"The price","example":123.45},"currencyCode":{"type":"string","description":"The currency code for the price","example":"EUR"},"countryCodes":{"type":"array","description":"The country codes for this region","examples":["DE","FR"],"items":{"type":"string"}},"firstBaseSupplied":{"type":"boolean","description":"Tells if SKU is Firstbase supplied","example":true}},"required":["countryCodes","currencyCode","firstBaseSupplied","price","priceOption","regionCode"]},"SimplifiedProductItemDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"SKU's internal ID","example":"123E4567-E89B-12D3-A456-426614174000"},"imageUrl":{"type":"string","description":"Presigned URL for the product image","example":"https://bucket.s3.amazonaws.com/image.jpg?X-Amz-Expires=86400"},"title":{"type":"string","description":"SKU's title","example":"MacBook Air 13\" M3 8-Core CPU 10-Core GPU 8GB RAM 512GB SSD - US / English - Space Gray - AU Plug"},"vendorSku":{"type":"string","description":"SKU's vendor SKU value","example":"123E4567-E89B-12D3-A456-426614174000"},"vendorCode":{"type":"string","description":"SKU's vendor's code","example":"APPLE"},"partNumber":{"type":"string","description":"SKU's part number","example":"MZ-1234HG"},"isStandardCatalog":{"type":"boolean","description":"Tells if the SKU is part of org's standard catalog","example":true},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"SKU's structured metadata"},"pricing":{"type":"array","description":"SKU's pricing details","items":{"$ref":"#/components/schemas/ProductPriceDetails"}},"stock":{"type":"array","description":"List of regions where this product is available","items":{"$ref":"#/components/schemas/StockDetailsDTO"}},"categoryCode":{"type":"string","description":"The category code for this product","example":"COMPUTER"},"categoryNameOfSku":{"type":"string","description":"The category name for this product","example":"Computer"}},"required":["categoryCode","categoryNameOfSku","id","isStandardCatalog","metadata","pricing","stock","title","vendorCode","vendorSku"]},"StockDetailsDTO":{"type":"object","properties":{"regionCode":{"type":"string","description":"Region where this product is available","example":"EU"},"countryCodes":{"type":"array","description":"List of countries where this product is available","examples":["DE","FR"],"items":{"type":"string"}},"availability":{"type":"array","description":"List of stock  availability details","items":{"$ref":"#/components/schemas/AvailabilityDTO"}}},"required":["availability","countryCodes","regionCode"]}},"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Prefix the value with \"ApiKey\" to indicate the custom authorization type","name":"Authorization","in":"header"}}}}