Skip to main content

Supported Use Cases for the Firstbase API

Updated

Today, our Firstbase API supports the following use cases:

  • Users: View, Create (Onboarding), Delete (Offboarding), Update.
  • Inventory: View.
  • Packages: View.
  • Orders: View, Create.
  • Catalog: View.

Most customers that use our API directly are using it to integrate with Firstbase to solve for the following needs:

  • HRIS Use Cases: Account provisioning (onboarding), updating and de-provisioning (offboarding).
  • ITSM Use Cases: Getting details and updates on inventory tracked in Firstbase. 
  • Catalog & Ordering Use Cases. Viewing the Firstbase catalog and placing orders via API. 

Planning your integration will allow you to cover all your bases when starting with the Firstbase API. Below we have listed some of the key questions you should review before you implement.

1. HRIS use cases

Account Provisioning  (Onboarding employees to Firstbase)

To onboard a new employee, retrieve Firstbase Package IDs with a GET request to /API/packages. Then, make a POST request to the /scim/v2/users endpoint to create new accounts. 

Important notes:

  • Mapping Packages: You’ll need to assign a Firstbase Package ID to a user for them to get an invite and be able to log in to place an order. Generally, our customers maintain a mapping between Packages & HRIS metadata like department or country.
  • Assigning emails: Only the “primary” email can be used to log in. Please use a personal email when onboarding someone who does not yet have access to a work email. 
  • Automatic orders: A mailing address is required when assigning someone a package configured with the “Automatic Order” status. An order will be sent immediately after the account is created.
  • Start dates required: Firstbase needs the employee start date to optimize delivery.
  • Employee’s country required: Even if you can’t provide the complete mailing address for a user, you must provide the country. Firstbase needs the employee’s country of residence for billing purposes.

Updating employee records

To keep employees’ names, emails, contact info, etc., up to date — or to change their Package assignment or login email — make a PUT request to the /scim/v2/users endpoint.

De-Provisioning (Offboarding employees)

To offboard an employee, make a DELETE request to the /scim/v2/users endpoint. If you don’t have the Firstbase user ID for the employee saved, you must retrieve it from /scim/v2/users. You can filter by email, given, or family name (docs here).

Important notes:

  • Starts the offboarding process: DELETE events will not lead to immediate hard data deletion from Firstbase. Instead, accounts will be put into “offboarding mode.” Users will be emailed a request to start the return process for any equipment assigned to them. They will no longer be able to place orders but can still log into Firstbase to complete their offboarding.
  • No scheduling option via API: Making a DELETE request will immediately trigger an offboarding request for the account. However, this is effectively the same result as scheduling an offboarding via the UI. The user gets the same email and has the same access to log in and confirm return kit shipping details.

2. Inventory use cases

Getting all Inventory in Firstbase

Our Inventory API will allow you to retrieve a list of all inventory items tracked via Firstbase. 

To get a list of inventory tracked in Firstbase, start by retrieving all Firstbase inventory with a GET request to /API/inventory. 

Information available includes:

  • Serial Number
  • Person Assigned
  • Deploy Status (e.g. Available, Deployed, Unavailable, Archived)
  • Deploy Reason (e.g. Gifted by Employer, Lost in Transit, Return in Progress, etc.). 
  • Condition (e.g. New, Used-Good, Used-Poor, etc.)

Here's an example response:


[
{
"id": "ecb7e933-de1e-9830-b180-b25d1d0d296e",
"skuId": "203a5df2-423a-43a9-bb19-1ccaf3434b91",
"serialNumber": "25f2e6ea9a",
"deployStatus": "ARCHIVED",
"deployReason": "LOST_BY_WORKER",
"condition": "NEW",
"categoryCode": "TSHIRT",
"categoryNameOfSku": "T-shirt",
"skuTitle": "T-shirt White - 5XL",
"vendorCode": "AWESOME_MERCHANDISE",
"vendorSku": "TSHRT_5XL_WHITE",
"createdAt": "2024-10-30T16:39:03.436Z",
"updatedAt": "2024-10-30T16:39:03.436Z",
"renewalDate": "2026-02-09",
"renewalDateUpdatedBy": "o",
"billingStartDate": "2026-02-09",
"billingEndDate": "2028-02-09",
"procurementMethod": "Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c",
"returnOrder": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "PENDING",
"createdAt": "2024-10-30T16:39:03.436Z",
"returnOrderItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"returnOrderItemStatus": "PENDING",
"retrievalMethod": {
"type": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "REQUESTED",
"inboundTrackingCode": "string",
"inboundTrackingLink": "string",
"outboundTrackingCode": "string",
"outboundTrackingLink": "string",
"updatedAt": "2024-10-30T16:39:03.436Z"
}
},
"assignedTo": {
"id": "371da231-5878-45b1-80a3-9113f8795c29",
"type": "PERSON",
"label": "San Francisco's office",
"assignedAt": "2024-10-30T16:39:03.436Z"
},
"tags": [
{
"id": "8e0caa73-cc71-4aa4-88eb-fca494de8e20",
"label": "Engineering"
}
],
"pricing": {
"regionCode": "string",
"priceOption": "string",
"price": 0,
"currencyCode": "string"
}
}
]

Updating Inventory in Firstbase

Our Inventory API will allow you to update specific inventory items tracked via Firstbase. 

To get a list of inventory tracked in Firstbase, start by retrieving all Firstbase inventory with a GET request to /API/inventory. Then you can update inventory using the PATCH/API/Inventory endpoint using a specific inventory ID. 

Information that can be updated for an asset includes:

  • Deploy Status (e.g. Available, Deployed, Unavailable, Archived)
  • Deploy Reason (e.g. Gifted by Employer, Lost in Transit, Return in Progress, etc.). 
  • Condition (e.g. New, Used)
  • Assignment (e.g. Person or Office location)

Here's an example request:

{
  "deployStatus": "ARCHIVED",
  "deployReason": "GIFTED_BY_EMPLOYER",
  "assignedTo": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "OFFICE"
  },
  "condition": "NEW"
}

The following schema considerations apply to the PATCH endpoint:

  • Deploy status can be changed for assets assigned to a person or an office in most cases, and not to assets in a warehouse location. 
  • Deploy reasons are based on the deployed status used. Available reasons are in the list below. 
  • Conditions available include: "NEW, USED"

Adding or deleting Tags for Assets in Firstbase

Our Inventory API will allow you to add or delete tags for assets tracked via Firstbase.

  • Use the POST/api/inventory/{inventoryID}/tags endpoint to submit tags for specific assets. 
  • Use the DELETE/api/inventory/{inventoryID}/tags to delete tags from specific assets.

Getting Returns Information via the API

In addition to relevant inventory information, the inventory API also provides returns information for inventory items, when applicable. 

When the return process starts for an inventory item, the inventory will have a "Deployed" deploy status, and it's still considered assigned to the employee.

In these cases, to denote it's in the process of being returned, we will automatically add a deploy reason of "Return in Progress".  

The following information is also available via the API when items have this deploy reason of "Return in Progress"

  • Return Order ID - Refers to the entire Return Order. 
  • Return Order Status (e.g. Submitted, Confirmed, Processing, Completed, Cancelled)
  • Return Order Item ID - Refers to a specific inventory item within the return order. 
  • Return Order Item Status (e.g. Pending, Returned, Not Returned, Cancelled)
  • Retrieval Method Type - Refers to the type of return. There's three types we consider today:
    • INBOUND_LABEL - Includes an inbound return send from the user to Firstbase. Does not include a return kit sent to the user beforehand. Has only inbound tracking.
    • RETURN_KIT - Includes a return kit being sent to the user, and then sent back from the user. Has both outbound and inbound tracking. 
    • PHYSICAL - White Label process for Heavy-Bulky Items like desks or chairs.
  • Retrieval Method Status (e.g. Requested, Label Created, Sent, Sent Back, Arrived at Processing Facility, etc.). 
  • Tracking Codes dependent on retrieval method. 
  • Updated at timestamp.

3. Catalog and Ordering Use Cases

Querying the Firstbase Catalog

To query the Firstbase Catalog, you can submit a GET request to our /API/catalog/skus endpoint. 

The API will provide three types of information on your catalog's content:

  • SKU Information: This includes the SKU ID, Title, Part Number and SKU Metadata (if available)
  • SKU Pricing Information: this includes the pricing per region
  • SKU Availability Information: this includes your current stock availability for this SKU per region, along with the condition of the devices available. 

If you'd want, you can also query for a specific catalog SKU by submitting a request to our /API/catalog/skus/{sku_id} endpoint.  

The catalog endpoint can be used together with the POST/API/orders endpoint to place orders in Firstbase for users, by submitting the SKU ID in the API call.  

Sample Response:

[
  {
    "id": "ecb7e933-de1e-9830-b180-b25d1d0d296e",
    "skuId": "203a5df2-423a-43a9-bb19-1ccaf3434b91",
    "serialNumber": "25f2e6ea9a",
    "deployStatus": "ARCHIVED",
    "deployReason": "LOST_BY_WORKER",
    "condition": "NEW",
    "categoryCode": "TSHIRT",
    "categoryNameOfSku": "T-shirt",
    "skuTitle": "T-shirt White - 5XL",
    "vendorCode": "AWESOME_MERCHANDISE",
    "vendorSku": "TSHRT_5XL_WHITE",
    "createdAt": "2024-10-30T16:39:03.436Z",
    "updatedAt": "2024-10-30T16:39:03.436Z",
    "renewalDate": "2026-02-09",
    "renewalDateUpdatedBy": "o",
    "billingStartDate": "2026-02-09",
    "billingEndDate": "2028-02-09",
    "procurementMethod": "Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c",
    "returnOrder": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "PENDING",
      "createdAt": "2024-10-30T16:39:03.436Z",
      "returnOrderItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "returnOrderItemStatus": "PENDING",
      "retrievalMethod": {
        "type": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "status": "REQUESTED",
        "inboundTrackingCode": "string",
        "inboundTrackingLink": "string",
        "outboundTrackingCode": "string",
        "outboundTrackingLink": "string",
        "updatedAt": "2024-10-30T16:39:03.436Z"
      }
    },
    "assignedTo": {
      "id": "371da231-5878-45b1-80a3-9113f8795c29",
      "type": "PERSON",
      "label": "San Francisco's office",
      "assignedAt": "2024-10-30T16:39:03.436Z"
    },
    "tags": [
      {
        "id": "8e0caa73-cc71-4aa4-88eb-fca494de8e20",
        "label": "Engineering"
      }
    ],
    "pricing": {
      "regionCode": "string",
      "priceOption": "string",
      "price": 0,
      "currencyCode": "string"
    }
  }
]

Placing Order Details

To place an order, you can use submit a POST request to our /API/orders endpoint. The request body needs to have the shipping address, the person ID, and the SKU ID to order (which you can get from the catalog endpoint). You can also submit whether the order should be expedited or not and your preferred condition. 

{
"shippingAddress": {
"addressLine1": "string",
"addressLine2": "string",
"administrativeArea": "string",
"countryCode": "string",
"dependentLocality": "string",
"locality": "string",
"postalCode": "string",
"sortingCode": "string",
"phoneNumber": "string"
},
"personId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"skus": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"expeditedShippingOption": "EXPEDITED_STANDARD",
"preferredCondition": "NEW"
}
]
}

The response will include the order id for the order placed:

Querying Order Details

To query all your orders, you can submit a GET request to our /API/Orders endpoint. The response will include all of your orders placed in Firstbase.

The response will include:

  • Order ID - ID for the overall order. 
  • Order Status - For the overall order (e.g. Partially shipped)
  • Order Item ID - ID for each item that is part of an order
  • Order Item Status - Status for each item that is part of the order (e.g. Delivered, Shipped)
  • Order Item Tracking URL - For each item in the order

To query for specific order details, you can submit a GET request to our /API/Orders/{orderID} endpoint. Similarly to the Get/Orders endpoint, the response will include:

  • Order ID - ID for the overall order. 
  • Order Status - For the overall order (e.g. Partially shipped)
  • Order Item ID - ID for each item that is part of an order
  • Order Item Status - Status for each item that is part of the order (e.g. Delivered, Shipped)
  • Order Item Tracking URL - For each item in the order

 

Related articles

Comments

0 comments

Please sign in to leave a comment.