# Firstbase API

> Integration endpoints for provisioning, inventory, orders, and people management.

- [Rate limits](https://developers.firstbase.com/rate-limits.md): Per-key quotas, response headers, 429 body, and recommended client backoff.
- [List categories](https://developers.firstbase.com/api-reference/catalog/list-categories.md): Returns the list of product categories available for asset creation. Use the category code when creating assets without a specific SKU. Optionally filter by code, name (case-insensitive partial match), or active status.
- [Get SKU](https://developers.firstbase.com/api-reference/catalog/get-sku.md): Returns pricing and availability details for a single SKU available to the caller's organization. Returns 404 if the SKU does not exist or is not available to this organization.
- [List SKUs](https://developers.firstbase.com/api-reference/catalog/list-skus.md): Returns a paginated list of SKUs (stock-keeping units) available to the caller's organization for ordering. Each SKU represents a purchasable product variant with pricing and availability information. Optionally filter by category code (e.g. COMPUTER, MONITOR, HEADSET) to narrow results.
- [List brands](https://developers.firstbase.com/api-reference/catalog/list-brands.md): Returns the list of brands available for asset creation. Use the brand code when creating assets with category_code. Optionally filter by code, name (case-insensitive partial match), or active status.
- [Add tags](https://developers.firstbase.com/api-reference/inventory/add-tags.md): Adds one or more tags to an inventory item. Tags are key-value labels used to organize and filter inventory. Existing tags with the same key are not replaced — duplicates are ignored.
- [Create asset](https://developers.firstbase.com/api-reference/inventory/create-asset.md): Creates a new asset (inventory item) in the organization's inventory. Identify the product either by sku_id (for known SKUs) or by category_code + description (for custom products). Assign the asset to a person (person_id) or an office (office_id).
- [Get inventory item](https://developers.firstbase.com/api-reference/inventory/get-inventory-item.md): Returns full details for a single inventory item belonging to the caller's organization. Returns 400 if the inventory does not belong to the organization.
- [Update inventory](https://developers.firstbase.com/api-reference/inventory/update-inventory.md): Partially updates inventory attributes for a single item owned by the caller's organization. Only fields present in the body are changed.
- [List inventory](https://developers.firstbase.com/api-reference/inventory/list-inventory.md): Returns a paginated list of inventory items owned by the caller's organization. Supports filtering by deploy status, person, office, category, and more. Results are sorted by creation date descending by default. Deprecated deploy statuses (GIFTED, LOCKED, OUT_FOR_REPAIR) are rejected with 400.
- [Remove tag](https://developers.firstbase.com/api-reference/inventory/remove-tag.md): Removes a single tag from an inventory item. Idempotent for missing tags is not guaranteed; a missing item returns 404.
- [List inventory levels](https://developers.firstbase.com/api-reference/inventory-levels/list-inventory-levels.md): Returns a paginated list of inventory level configurations (min/max stock rules) for the caller's organization. Each record defines the minimum and maximum quantity thresholds for a specific SKU at a specific warehouse. Supports filtering by SKU, warehouse, region, category, brand, and active status…
- [Create inventory level](https://developers.firstbase.com/api-reference/inventory-levels/create-inventory-level.md): Creates an inventory level configuration that defines the minimum and maximum stock thresholds for a specific SKU at a specific warehouse. Optionally scoped to a region. Returns 409 if a level already exists for the same SKU + warehouse + region combination.
- [Update inventory level](https://developers.firstbase.com/api-reference/inventory-levels/update-inventory-level.md): Partial update for inventory level thresholds and reordering settings.
- [Delete inventory level](https://developers.firstbase.com/api-reference/inventory-levels/delete-inventory-level.md): Soft-deletes (deactivates) an inventory level configuration. The record is not permanently removed; reactivation requires creating a new configuration via POST.
- [List inventory orders](https://developers.firstbase.com/api-reference/inventory-orders/list-inventory-orders.md): Returns a paginated list of inventory orders (warehouse stock replenishment requests) for the caller's organization. Supports filtering by status and date range, and sorting by creation date. Each result includes the ordered items and their shipment details.
- [Create inventory order](https://developers.firstbase.com/api-reference/inventory-orders/create-inventory-order.md): Creates an inventory order to ship equipment from a supplier or customer to a Firstbase warehouse. Specify the destination warehouse and the items (SKUs with quantities) to be stocked. The created order begins in SUBMITTED status and will be processed by the Firstbase logistics team.
- [Modify inventory order](https://developers.firstbase.com/api-reference/inventory-orders/modify-inventory-order.md): Partially update an inventory order. Field writability depends on order status — see request body schema.
- [Cancel inventory order](https://developers.firstbase.com/api-reference/inventory-orders/cancel-inventory-order.md): Cancels an inventory order. Allowed only when the order is in SUBMITTED status.
- [Get inventory order](https://developers.firstbase.com/api-reference/inventory-orders/get-inventory-order.md): Returns a single inventory order (including items and shipments) belonging to the caller's organization.
- [List ITAD requests](https://developers.firstbase.com/api-reference/itad/list-itad-requests.md): Returns a paginated list of ITAD (IT Asset Disposition) requests for the organization. Each request represents a scheduled disposition event for one or more inventory items. Use query parameters to filter by status or date range.
- [Create ITAD requests](https://developers.firstbase.com/api-reference/itad/create-itad-requests.md): Create ITAD requests from a list of inventory IDs. Items are automatically grouped by warehouse, creating one request per warehouse.
- [Get ITAD request](https://developers.firstbase.com/api-reference/itad/get-itad-request.md): Returns full details for a single IT Asset Disposition (ITAD) request belonging to the caller's organization, including all items in the request and their individual disposition statuses.
- [List eligible assets](https://developers.firstbase.com/api-reference/itad/list-eligible-assets.md): List inventory assets eligible for ITAD disposition. Eligibility is based on category, deploy status, and other criteria.
- [Send reminder](https://developers.firstbase.com/api-reference/new-joiners/send-reminder.md): Sends a reminder email to the specified new joiner. Optionally records the sender person for audit purposes.
- [Get new joiner stats](https://developers.firstbase.com/api-reference/new-joiners/get-new-joiner-stats.md): Aggregate counts for status cards and provisioning outcomes. Accepts the same filter query parameters as the list endpoint (e.g. countryCodes, equipmentReadiness, urgency) so stats reflect the filtered cohort. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply…
- [List new joiners](https://developers.firstbase.com/api-reference/new-joiners/list-new-joiners.md): Paginated, filterable, sortable list of new joiner rows for the organization. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply it explicitly to widen the window beyond 60 days.
- [Modify office](https://developers.firstbase.com/api-reference/offices/modify-office.md): Partially update an office. Modifiable fields: `name`, `contactName`, `address` (full-object replace when present), `active`. Setting `active=false` soft-deletes the office. Reactivation (`active=true`) is not supported and returns 400. Business-rule rejections (active inventory, active return order…
- [Get office](https://developers.firstbase.com/api-reference/offices/get-office.md): Returns full details for a single office belonging to the caller's organization.
- [List offices](https://developers.firstbase.com/api-reference/offices/list-offices.md): Returns a paginated list of offices belonging to the caller's organization. Supports pagination. Active and inactive offices are both returned unless filtered.
- [Decline order](https://developers.firstbase.com/api-reference/orders/decline-order.md): 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.
- [Approve order](https://developers.firstbase.com/api-reference/orders/approve-order.md): 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.
- [List orders](https://developers.firstbase.com/api-reference/orders/list-orders.md): Returns a paginated list of orders belonging to the caller's organization. Supports filtering by person, date range, status, and sorting. Results are sorted by creation date ascending by default.
- [Create order](https://developers.firstbase.com/api-reference/orders/create-order.md): Places a new order for one or more SKUs, delivered to either a person or an office. Exactly one of `personId` or `officeId` must be provided. Shipping address is auto-resolved from the recipient when not explicitly supplied. Returns the newly created order, including its ID and initial status.
- [Get order](https://developers.firstbase.com/api-reference/orders/get-order.md): Returns full details for a single order belonging to the caller's organization, including order items, current status, and shipping address.
- [Modify order](https://developers.firstbase.com/api-reference/orders/modify-order.md): Partially update an existing order. Allowed before fulfilment. Modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId, status (CANCELLED only). Address validation workflow is unchanged by this endpoint (same as logistics modify-order: `addressValidationNeeded` is not set…
- [List packages](https://developers.firstbase.com/api-reference/packages/list-packages.md): Returns a paginated list of equipment packages (onboarding bundles) belonging to the caller's organization. Each package contains SKUs and rules that determine what equipment new joiners receive automatically.
- [Create package](https://developers.firstbase.com/api-reference/packages/create-package.md): Creates a new equipment package (onboarding bundle) for the caller's organization. The package defines which SKUs are automatically ordered when a new joiner is onboarded. Gated by a feature flag; returns 403 when the flag is disabled.
- [Modify package note](https://developers.firstbase.com/api-reference/packages/modify-package-note.md): Partially update a single note attached to a package. Modifiable fields: `note`, `active`. Setting `active=false` soft-deletes the note. The response includes the full package view plus its `notes` collection (upsert semantics surfaced via the refreshed `notes` array).
- [Get package](https://developers.firstbase.com/api-reference/packages/get-package.md): Returns full details for a single equipment package identified by its URL-safe slug. Includes the package's SKUs, rules, notes, and configuration fields.
- [Modify package](https://developers.firstbase.com/api-reference/packages/modify-package.md): Partially update a package by slug. Modifiable scalar fields: `name`, `active`, `approvalRequired`, `automaticOrder`, `defaultOfficeId`, `deliverySetting`. When `skus` is present, each entry adds or removes a SKU by catalog `id` (set `delete: true` to unlink). Omitted existing SKUs are unchanged; om…
- [Get person](https://developers.firstbase.com/api-reference/people/get-person.md): Retrieves a person's SCIM representation by their internal Firstbase ID. Use the `attributes` or `excludedAttributes` query parameters to control which SCIM fields are included in the response.
- [Replace person](https://developers.firstbase.com/api-reference/people/replace-person.md): Performs a full replacement (PUT) of a person's SCIM attributes. All writable fields in the request body overwrite the existing values. Used by identity providers (IdPs) to keep person data in sync. Returns 409 if the updated `userName` conflicts with another existing user.
- [Delete user](https://developers.firstbase.com/api-reference/people/delete-user.md): 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
- [List people](https://developers.firstbase.com/api-reference/people/list-people.md): Returns a paginated SCIM ListResponse of people in the caller's organization. Filter by email address or name using SCIM filter expressions. Maximum of 50 users per page.
- [Create person](https://developers.firstbase.com/api-reference/people/create-person.md): Creates a new person record in Firstbase using the SCIM 2.0 protocol. Triggers automatic equipment ordering if the person is assigned to an active package. The `userName` field must be a unique email address. Returns 409 if a user with the same `userName` already exists.
- [Bulk upsert users](https://developers.firstbase.com/api-reference/people/bulk-upsert-users.md): Parses the CSV file and forwards it as a SCIM Bulk request to create and/or update users.
- [Bulk operations](https://developers.firstbase.com/api-reference/people/bulk-operations.md): Performs bulk operations using the SCIM protocol as defined by RFC 7644.
- [Reactivate person](https://developers.firstbase.com/api-reference/people/reactivate-person.md): Reactivates a previously offboarded person in the caller's organization. Restores the person for ordering and inventory assignment according to current organization settings.
- [Offboard person](https://developers.firstbase.com/api-reference/people/offboard-person.md): Starts offboarding for the person. May create return workflows depending on request body options (for example address confirmation and items not to return).
- [Send email](https://developers.firstbase.com/api-reference/people/send-email.md): Triggers an admin email action for the specified person. The `emailType` determines the action:
- [List regions](https://developers.firstbase.com/api-reference/regions/list-regions.md): Returns a paginated list of geographic regions associated with the caller's organization. Regions define where inventory levels apply and where warehouses operate. Optionally filter by region name (partial match) or region code. Page and size are 1-based and capped at 100 per page.
- [Get region](https://developers.firstbase.com/api-reference/regions/get-region.md): Returns full details for a single region accessible to the caller's organization.
- [List replacements](https://developers.firstbase.com/api-reference/replacements/list-replacements.md): Returns a paginated list of replacement orders for the organization. A replacement is created when a defective or lost device needs to be swapped for a new one.
- [Create replacement](https://developers.firstbase.com/api-reference/replacements/create-replacement.md): Creates a replacement consisting of a return order and a new equipment order
- [Get replacement](https://developers.firstbase.com/api-reference/replacements/get-replacement.md): Returns the details of a single replacement order by its unique identifier.
- [Cancel replacement](https://developers.firstbase.com/api-reference/replacements/cancel-replacement.md): Cancels a replacement. Allowed only when status is SUBMITTED. Cascades to cancel the associated return order and releases any reserved inventory. Gated by the FBS_2976_PUBLIC_API_ENTITY_MODIFICATION feature flag.
- [List returns](https://developers.firstbase.com/api-reference/returns/list-returns.md): 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.
- [Create return](https://developers.firstbase.com/api-reference/returns/create-return.md): Creates a new return order for a person. Items can be identified by inventoryId or serialNumber. If officeId is provided, items are returned to the office (returnMethod forced to SHIPMENT). Otherwise items are returned to the Firstbase warehouse.
- [Process return items](https://developers.firstbase.com/api-reference/returns/process-return-items.md): Bulk-update items on a return order (used when items physically arrive). Each item: `id`, `status`. When `status` is NOT_RETURNED, send `notReturnedDisposition` DEPLOYED (keep deployed; omit deploy fields) or ARCHIVE (`deployReason` required; non-blank `deployReasonDetails` when deployReason is OTHE…
- [Get return](https://developers.firstbase.com/api-reference/returns/get-return.md): Returns full details for a single return order belonging to the caller's organization. Optionally includes shipment tracking information when includeShipment=true.
- [Cancel return](https://developers.firstbase.com/api-reference/returns/cancel-return.md): Cancels a return order. Allowed only when status is SUBMITTED or CONFIRMED. Releases inventory back to active state. Honors offboarding-vs-one-off branching.
- [Get shipment](https://developers.firstbase.com/api-reference/shipment/get-shipment.md): Returns shipment details for the provided tracking numbers, paginated. At least one tracking number must be supplied. Each result includes carrier, tracking status, and the order items associated with the shipment.
- [List carriers](https://developers.firstbase.com/api-reference/shipment/list-carriers.md): Returns supported carriers for shipment tracking. You can optionally filter carriers by tracking platform.
- [List shipment notices](https://developers.firstbase.com/api-reference/shipment-notices/list-shipment-notices.md): Returns a paginated list of shipment notice orders. V1 exposes a full `inventories` list per package item, replacing the single serial-number field in the legacy endpoint. Supports filtering by status, warehouse, and date range.
- [Create shipment notice](https://developers.firstbase.com/api-reference/shipment-notices/create-shipment-notice.md): Creates a new shipment notice order. Identify the source as SUPPLIER (with purchase_order_number) or OFFICE. Each shipment contains items identified by sku_id with a quantity.
- [Modify shipment notice](https://developers.firstbase.com/api-reference/shipment-notices/modify-shipment-notice.md): Partially updates a shipment notice and its packages/items. Editability follows the rule: shipment notice editable when SUBMITTED or PROCESSING with at least one PENDING package. Use `{id, delete: true}` on shipmentNoticePackages or items to remove them. Omit elements to preserve them. Add new packa…
- [Cancel shipment notice](https://developers.firstbase.com/api-reference/shipment-notices/cancel-shipment-notice.md): Cancels a shipment notice. Allowed only when notice status is SUBMITTED. Cascades all package item statuses to CANCELLED.
- [Get shipment notice](https://developers.firstbase.com/api-reference/shipment-notices/get-shipment-notice.md): Returns full details for a single shipment notice order belonging to the caller's organization. Each package item includes a full `inventories` list with individual serial numbers and inventory IDs.
- [List warehouses](https://developers.firstbase.com/api-reference/warehouses/list-warehouses.md): Returns a paginated list of Firstbase warehouses that the caller's organization can use when creating inventory orders or shipment notices. Optionally filter by country code (ISO 3166-1 alpha-2). Page and size are 1-based and capped at 100 per page.
- [Get warehouse](https://developers.firstbase.com/api-reference/warehouses/get-warehouse.md): Returns full details for a single warehouse accessible to the caller's organization.

## OpenAPI Specs

- [openapi](/openapi.json)

## Optional

- [Swagger UI](https://apipub.firstbasehq.com/swagger-ui/index.html)