cURL
curl -sS -X GET 'https://apipub.firstbasehq.com/api/v1/replacements?page=1&size=100&sortBy=createdAt&sortDirection=DESC' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json'import requests
url = "https://apipub.firstbasehq.com/api/v1/replacements"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://apipub.firstbasehq.com/api/v1/replacements', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));[
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "SUBMITTED",
"createdAt": "2025-01-15",
"person": {
"id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
"forename": "<string>",
"surname": "<string>"
},
"submittedBy": {
"id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
"forename": "<string>",
"surname": "<string>"
},
"order": {
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "COMPLETED",
"orderItems": [
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"skuId": "123E4567-E89B-12D3-A456-426614174000",
"title": "iPad Air - Silver, 64GB, WiFi",
"categoryCode": "COMPUTER",
"status": "PROCESSING",
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"shipment": {
"trackingUrl": "<string>",
"trackingCode": "1Z00000000",
"carrier": "UPS",
"status": "DELIVERED",
"trackingHistory": [
{
"status": "IN_TRANSIT",
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"submittedBy": "John S. (Firstbase)",
"approvedBy": "Jane Smith",
"approvedAt": "2026-02-26",
"deliverToOffice": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "NYC HQ",
"address": {
"countryCode": "US",
"addressLine1": "123 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
}
},
"deliverToPerson": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2026-02-26T14:15:22.123Z",
"updatedAt": "2026-03-15T09:00:00.000Z",
"expectedBy": "2026-03-10",
"packageSlug": "engineering-onboarding",
"deliveryLocation": "PERSON"
},
"returnOrder": {
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "COMPLETED",
"orderItems": [
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"skuId": "123E4567-E89B-12D3-A456-426614174000",
"title": "iPad Air - Silver, 64GB, WiFi",
"categoryCode": "COMPUTER",
"status": "PROCESSING",
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"shipment": {
"trackingUrl": "<string>",
"trackingCode": "1Z00000000",
"carrier": "UPS",
"status": "DELIVERED",
"trackingHistory": [
{
"status": "IN_TRANSIT",
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"submittedBy": "John S. (Firstbase)",
"approvedBy": "Jane Smith",
"approvedAt": "2026-02-26",
"deliverToOffice": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "NYC HQ",
"address": {
"countryCode": "US",
"addressLine1": "123 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
}
},
"deliverToPerson": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2026-02-26T14:15:22.123Z",
"updatedAt": "2026-03-15T09:00:00.000Z",
"expectedBy": "2026-03-10",
"packageSlug": "engineering-onboarding",
"deliveryLocation": "PERSON"
}
}
]{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Replacements
List replacements
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.
GET
https://apipub.firstbasehq.com
/
api
/
v1
/
replacements
cURL
curl -sS -X GET 'https://apipub.firstbasehq.com/api/v1/replacements?page=1&size=100&sortBy=createdAt&sortDirection=DESC' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json'import requests
url = "https://apipub.firstbasehq.com/api/v1/replacements"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://apipub.firstbasehq.com/api/v1/replacements', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));[
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "SUBMITTED",
"createdAt": "2025-01-15",
"person": {
"id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
"forename": "<string>",
"surname": "<string>"
},
"submittedBy": {
"id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
"forename": "<string>",
"surname": "<string>"
},
"order": {
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "COMPLETED",
"orderItems": [
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"skuId": "123E4567-E89B-12D3-A456-426614174000",
"title": "iPad Air - Silver, 64GB, WiFi",
"categoryCode": "COMPUTER",
"status": "PROCESSING",
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"shipment": {
"trackingUrl": "<string>",
"trackingCode": "1Z00000000",
"carrier": "UPS",
"status": "DELIVERED",
"trackingHistory": [
{
"status": "IN_TRANSIT",
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"submittedBy": "John S. (Firstbase)",
"approvedBy": "Jane Smith",
"approvedAt": "2026-02-26",
"deliverToOffice": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "NYC HQ",
"address": {
"countryCode": "US",
"addressLine1": "123 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
}
},
"deliverToPerson": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2026-02-26T14:15:22.123Z",
"updatedAt": "2026-03-15T09:00:00.000Z",
"expectedBy": "2026-03-10",
"packageSlug": "engineering-onboarding",
"deliveryLocation": "PERSON"
},
"returnOrder": {
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "COMPLETED",
"orderItems": [
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"skuId": "123E4567-E89B-12D3-A456-426614174000",
"title": "iPad Air - Silver, 64GB, WiFi",
"categoryCode": "COMPUTER",
"status": "PROCESSING",
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"shipment": {
"trackingUrl": "<string>",
"trackingCode": "1Z00000000",
"carrier": "UPS",
"status": "DELIVERED",
"trackingHistory": [
{
"status": "IN_TRANSIT",
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"submittedBy": "John S. (Firstbase)",
"approvedBy": "Jane Smith",
"approvedAt": "2026-02-26",
"deliverToOffice": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "NYC HQ",
"address": {
"countryCode": "US",
"addressLine1": "123 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
}
},
"deliverToPerson": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2026-02-26T14:15:22.123Z",
"updatedAt": "2026-03-15T09:00:00.000Z",
"expectedBy": "2026-03-10",
"packageSlug": "engineering-onboarding",
"deliveryLocation": "PERSON"
}
}
]{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Authorizations
Query Parameters
Filter by replacement order status (calculated from order and return statuses).
Filter by replacement order status (calculated from order and return statuses).
Available options:
SUBMITTED, PROCESSING, COMPLETED, PARTIALLY_COMPLETED, CANCELLED, SUBMITTED, PROCESSING, COMPLETED, PARTIALLY_COMPLETED, CANCELLED Filter by the shipment order status of the replacement's linked order.
Filter by the shipment order status of the replacement's linked order.
Available options:
AWAITING_APPROVAL, ORDERED, PROCESSING, ORDERED_NOT_SHIPPED, SHIPPED, COMPLETED, PARTIALLY_SHIPPED, DECLINED, AWAITING_DELIVERY_SCHEDULING, DELIVERY_SCHEDULED, DELIVERED, ACTIVATED, NONE, APPROVED, AWAITING_FULFILLMENT, ACTION_REQUIRED, 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, 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_DELIVERED, RETURN_KIT_SENT_BACK, RECEIVED_IN_WAREHOUSE, RETURNED, NOT_RETURNED, OUT_FOR_DELIVERY, DELIVERY_EXCEPTION, SUBMITTED, CANCELLED, CONFIRMED, NOT_COMPLETED, PARTIALLY_COMPLETED Filter by retrieval method (return kit) statuses.
Filter by retrieval method (return kit) statuses.
Available options:
REQUESTED, PROCESSED, CANCELLED, LABEL_CREATED, SHIPPED, DELIVERED, SENT_BACK, ARRIVED_AT_PROCESSING_FACILITY, DELIVERY_EXCEPTION, NOT_PROCESSED, PARTIALLY_PROCESSED, SCHEDULING_PICK_UP, REQUESTED, PROCESSED, CANCELLED, LABEL_CREATED, SHIPPED, DELIVERED, SENT_BACK, ARRIVED_AT_PROCESSING_FACILITY, DELIVERY_EXCEPTION, NOT_PROCESSED, PARTIALLY_PROCESSED, SCHEDULING_PICK_UP Response
A paginated list of replacement orders matching the filter criteria.