Firstbase API: What's available and how to use it

Introduction

The Firstbase API lets you automate your device lifecycle management workflows directly from your own systems. Instead of logging into Firstbase to process returns, create assets, manage packages, or update records, you can do it all programmatically.

This article covers what the Firstbase API supports today, so you know exactly what you can automate and where to get started.

API reference: Full endpoint documentation, request/response schemas, and error codes are available at apipub.firstbasehq.com/swagger-ui/index.html.

What You Can Do

Returns and Replacements

• Start a return order for an employee's equipment. Choose how equipment is returned: ship to a Firstbase warehouse (SHIP_TO_FIRSTBASE), ship to one of your offices (SHIP_TO_OFFICE), or have the employee drop it off at an office (DROPPED_TO_OFFICE).
• Create a replacement order to return old equipment and order new equipment in a single step. If either part fails, both are cancelled together so nothing falls through the cracks.
• Cancel a return or replacement order after it has been created, as long as it has not yet been processed.

Key endpoints:

• POST /api/v1/returns 
• PATCH /api/v1/return-orders/{returnOrderId}/items 
• DELETE /api/v1/returns/{id} 
• POST /api/v1/replacements 
• DELETE /api/v1/replacements/{id}

Warehouse Restocking (Inventory Orders)

• Place a restocking order to replenish a warehouse with specific products and quantities.
• Include a PO number, billing type, expected ship date, and notes for your records.
• Update or cancel a restocking order while it is still in submitted status. The PO number can be updated even after processing begins.

Key endpoints:

• POST /api/v1/inventory-orders 
• PATCH /api/v1/inventory-orders/{id} 
• DELETE /api/v1/inventory-orders/{id}

Inventory Levels

• Set minimum and maximum stock thresholds for a product at a specific warehouse. When stock drops below the minimum and auto-restock is on, Firstbase will automatically create a new restocking order.
• Update thresholds at any time, or remove a threshold configuration entirely.

Key endpoints:

• POST /api/v1/inventory-levels 
• PATCH /api/v1/inventory-levels/{id} 
• DELETE /api/v1/inventory-levels/{id}

Asset Creation

• Add an individually purchased asset to your Firstbase inventory and assign it to a person or office. Identify the product by SKU or by category and description.
• Specify serial number, condition, and renewal date at creation time.

Key endpoints:

• POST /api/v1/assets

Shipment Notices

• Notify Firstbase in advance that equipment is on its way to a warehouse from a supplier or one of your offices. Include per-package tracking information and item quantities.
• Update or cancel a shipment notice after creation while it is still in submitted status.

Key endpoints:

• POST /api/v1/shipment-notices 
• PATCH /api/v1/shipment-notices/{id} 
• DELETE /api/v1/shipment-notices/{id}

Package Management

• Create an equipment bundle with category rules, specific products, delivery settings, and approval requirements.
• Update any package configuration after creation, including the name, products, rules, and delivery settings.

Key endpoints:

• POST /api/v1/packages 
• PATCH /api/v1/packages/{slug}

Offboarding and Reactivation

• Offboard an employee using one of three return types: ship to a Firstbase warehouse (SHIP_TO_FIRSTBASE), ship to one of your offices (SHIP_TO_OFFICE), or have the employee drop equipment off at an office (DROPPED_TO_OFFICE). Specify which items to return, which to keep, and whether the employee needs to confirm their shipping address.
• Reactivate an offboarded or inactive employee, which automatically cancels any associated return orders.

Key endpoints:

• POST /api/v1/people/{personId}/offboard 
• POST /api/v1/people/{personId}/reactivate

Querying and Filtering

• List and filter across all major resources: orders, returns, replacements, restocking orders, inventory levels, assets, shipment notices, packages, and offices.
• Filter by status, date ranges, categories, products, serial numbers, person, country, and more.
• Sort results on all list endpoints.

Key endpoints:

• GET /api/v1/orders 
• GET /api/v1/returns 
• GET /api/v1/replacements 
• GET /api/v1/inventory-orders 
• GET /api/v1/inventory 
• GET /api/v1/shipment-notices 
• GET /api/v1/packages 
• GET /api/v1/offices

Updating and Cancelling Existing Records

• Update orders, return order items, assets, packages, offices, restocking orders, inventory levels, and shipment notices after they have been created.
• Cancel orders, return orders, replacements, restocking orders, and shipment notices programmatically.

Frequently Asked Questions

Can I use the API to offboard employees?

Yes. The offboard endpoint lets you initiate the full offboarding workflow for an employee without logging into Firstbase. You specify the employee, their last working date, which items to return or keep, and one of three return types:

• SHIP_TO_FIRSTBASE - Equipment is shipped to a Firstbase warehouse.
• SHIP_TO_OFFICE - Equipment is shipped to one of your offices. Requires an officeId.
• DROPPED_TO_OFFICE - Employee drops equipment off directly at an office. Requires an officeId.

A few things to know:

• Subscription equipment must be returned. The API will reject the request if you try to mark subscription items as "not returning."
• Giftable items are handled automatically. If your organization has categories configured as giftable, those items are gifted to the employee automatically. You do not need to include or exclude them.
• Ineligible items cannot be returned. Equipment that is archived, on hold, or already in a return cannot be included.
• If there are no items to return and you do not need address confirmation, the employee transitions directly to inactive status with no return order created.

What is the difference between using the offboard endpoint and creating a return manually?

These two approaches serve different purposes and should not be used interchangeably.

The offboard endpoint is for when an employee is leaving your company. It handles the complete departure workflow: it updates the employee's status, automatically gifts eligible equipment, creates the return order for remaining items, and ensures everything is processed correctly. Always use the offboard endpoint when someone is leaving.

The create return endpoint is for one-off equipment retrievals that are not related to someone leaving. For example, retrieving a damaged laptop for replacement or collecting equipment from an employee who is staying at the company.

Using the create return endpoint for an offboarding scenario will not update the employee's status or handle subscription and giftable item logic correctly.

Can I update or cancel records after they have been created?

Yes, depending on the type of record and its current status:

• Orders - Update products, shipping address, or delivery destination while the order is in awaiting approval, approved, or ordered status. You can cancel individual line items or the entire order.
• Return orders - Update individual item statuses when processing returns received at an office. Cancel a return order while it is in submitted or confirmed status.
• Replacement orders - Cancel while in submitted status.
• Restocking orders - Update all fields while in submitted status. Update the PO number even after processing begins. Cancel while in submitted status.
• Inventory levels - Update thresholds and settings at any time.
• Packages - Update any configuration at any time.
• Offices - Update name, contact, address, and active status, subject to whether equipment or active return orders are linked to the office.
• Shipment notices - Update while in submitted status. Individual packages can still be updated while in pending status even after the notice moves to processing. Cancel while in submitted status.

What return reasons can I use via the API?

Return and replacement reasons are different sets.

For returns, the following reasons are supported:

• FULFILLMENT_ERROR - Person received incorrect item
• OFF_CYCLE - Person no longer needs item
• DAMAGED - Item is damaged or malfunctioning
• OTHER - Other

For replacements, the following reasons are supported:

• FULFILLMENT_ERROR - Person received incorrect item
• DAMAGED - Item is damaged or malfunctioning
• UPGRADE - Eligible for an upgrade
• STANDARD_LIFECYCLE - Requires lifecycle replacement
• PRODUCT_CHANGE - Prefers a different item
• LOST_BY_WORKER - Person lost item
• LOST_BY_PARTNER - Item was lost in transit
• OTHER - Other

Note: OFFBOARDING is not available via either endpoint. Use the dedicated offboard endpoint when an employee is leaving your company.

Can I add equipment that I purchased outside of Firstbase?

Yes. You can add individually purchased assets to your Firstbase inventory using the API. There are two ways to identify the product:

• By SKU: Use a specific SKU from your Firstbase catalog.
• By category and description: Provide a category code, an optional brand code, and a product description. Firstbase will match or create the appropriate product record automatically.

The asset must be assigned to a person or office at creation time. You can also include the serial number, condition (NEW or USED), and renewal date.

To look up valid values:

• SKUs: Use GET /api/catalog/skus
• Category codes: Use GET /api/v1/categories
• Brand codes: Use GET /api/v1/brands

Where do I find valid category codes and brand codes for creating assets?

Both have dedicated lookup endpoints:

• Category codes: GET /api/v1/categories returns a paginated list of all product categories available to your organization. Filter by code or name. Use the code value from the response when creating assets.
• Brand codes: GET /api/v1/brands returns a paginated list of all brands available to your organization. Filter by code or name. Use the code value from the response when creating assets.

What happens if I try to update an inventory order that is already being processed?

Once an inventory order moves past submitted status, only the PO number can be updated. Sending any other field (warehouse, region, billing type, or items) on an order that is in processing or shipped status returns a 409 error.

To update the PO number on a processing or shipped order, send only the customerPoNumber field in your request and omit everything else.

What happens to giftable items when I offboard an employee via the API?

Giftable items are handled automatically. Some equipment categories are configured as giftable by default by Firstbase, and your organization may have additional categories configured as giftable as well. During offboarding, any item in a giftable category is automatically gifted to the employee without any action needed from you. These items are marked as archived with a reason of "gifted by employer."

You do not need to include or exclude giftable items in your request. If you explicitly include a giftable item in the list of items to return, the request will be rejected.

If you are unsure which categories are configured as giftable for your organization, reach out to your Customer Success Manager. If you want to change which categories are giftable, contact Firstbase Support.

Can I update subscription equipment through the API?

Only tags can be added or removed on subscription equipment. All other fields such as serial number, condition, description, brand, assignment, and renewal date are read-only for subscription assets. Attempting to modify any other field on a subscription asset returns a 409 error.

Purchased equipment, whether you supplied it or Firstbase supplied it, supports a broader set of editable fields depending on its current assignment and return status.

Can I elect ITAD for returned equipment via the API?

Yes, with the following restrictions:

• ITAD can only be elected for warehouse returns. It is not available for returns to an office or drop-offs.
• ITAD is not available for subscription equipment.
• ITAD is only supported for equipment in these categories: computers, mobile phones, drawing tablets, tablets, and external hard drives.

To elect ITAD for an item, set itad: true on that item when creating a return or offboarding an employee.

Where can I find the full API documentation?

The full API documentation is available at apipub.firstbasehq.com/swagger-ui/index.html. All endpoints are documented with request and response schemas, field descriptions, and error codes. You can also use the Swagger UI to test endpoints directly.

Coming soon: We are building a dedicated developer experience website that will make it easier to explore and test the Firstbase API. We plan to launch it in the next couple of weeks.

If you need help or have questions, contact your Customer Success Manager.

What is the difference between offboarding and deleting an employee via the API?

There are two ways to trigger an employee departure via the API and they behave differently.

Offboarding is the recommended approach for when an employee is leaving your company. It initiates a structured departure workflow where you specify the equipment to return, the return type, the employee's last working date, and how to handle each asset. It enforces all the same subscription, gifting, and ITAD rules as the Firstbase platform. The employee record is preserved and can be reactivated later if needed.

SCIM Delete (DELETE /scim/v2/Users/{id}) is a soft delete that also triggers offboarding. If you have an HR or identity system integration (such as Okta or Azure AD), deletions triggered from that system will use this path. It does not allow you to specify which items to return or how to handle each asset. The platform handles equipment automatically based on your organization's defaults.

Now that the dedicated offboard endpoint is available, we recommend using it for offboarding workflows as it gives you full control over the process. SCIM Delete is best suited for automated identity lifecycle integrations where departures are triggered directly from your HR system.