Presentation
The StageReturn public API is a read-only lookup API. The API key automatically determines which company’s data can be accessed.
- Format of answers: JSON
- Protocol : HTTPS
- Authentication: header x-api-key
- Accepted method: GET
- Case Body : none
- Parameters : passed in URL query string
This page documents only the two public endpoints that are actually available: equipmentStatusApi and missingEquipmentStatusApi.
Base URL
The official URL for the StageReturn API is:
Base URL
https://api.stagereturn.com
This address is the official entry point for the StageReturn API. All cases documented below use this domain.
The available public endpoints are :
Endpoints
GET /equipmentStatusApi GET /missingEquipmentStatusApi
Case Format
- Use the method GET.
- Pass the parameters into the URL.
- Don’t send any case bodies.
- Send the key in the header x-api-key.
- Header Accept: application/json est recommandé.
- Encode the parameters with URL encoding.
Exemple HTTP
GET /equipmentStatusApi?serial=SN-123456 HTTP/1.1 Host: api.stagereturn.com x-api-key: YOUR_API_KEY Accept: application/json
Authentication
Each request must send a valid StageReturn API key in the HTTP header x-api-key.
Header requis
x-api-key: YOUR_API_KEY
The key must be sent as is, without a prefix Bearer.
Obtain an API key
In StageReturn, open the administration area and then the section API. The key must be generated and activated by an authorized corporate user.
Keep the server-side key. Do not integrate it into a public site, frontend application, or an accessible code repository.
First call
This first call checks the status associated with the serial number SN-123456.
cURL
Bash
curl --request GET \ --url "https://api.stagereturn.com/equipmentStatusApi?serial=SN-123456" \ --header "x-api-key: YOUR_API_KEY" \ --header "Accept: application/json"
JavaScript / Node.js
JavaScript
const url = new URL(
"https://api.stagereturn.com/equipmentStatusApi"
);
url.searchParams.set("serial", "SN-123456");
const response = await fetch(url, {
method: "GET",
headers: {
"x-api-key": process.env.STAGERETURN_API_KEY,
"Accept": "application/json"
}
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.error || `HTTP ${response.status}`);
}
console.log(data);
PHP
PHP
<?php
$serial = rawurlencode("SN-123456");
$url = "https://api.stagereturn.com/equipmentStatusApi?serial={$serial}";
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"x-api-key: " . getenv("STAGERETURN_API_KEY"),
"Accept: application/json"
],
CURLOPT_TIMEOUT => 15
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($body, true);
if ($status < 200 || $status >= 300) {
throw new Exception($data["error"] ?? "HTTP {$status}");
}
Python
Python
import os
import requests
response = requests.get(
"https://api.stagereturn.com/equipmentStatusApi",
params={"serial": "SN-123456"},
headers={
"x-api-key": os.environ["STAGERETURN_API_KEY"],
"Accept": "application/json",
},
timeout=15,
)
data = response.json()
if not response.ok:
raise RuntimeError(data.get("error", f"HTTP {response.status_code}"))
print(data)
GET
/equipmentStatusApi?serial=XXXX
Check the status of serialized equipment
Searches up to 10 open company repairs for the serial number provided. A repair is considered open when its status is todo or in_progress.
If multiple open repairs match the same serial number, a repair that immobilizes equipment takes priority. If no open repair immobilizes it, the API returns the information of the first open repair found.
Query parameter
| Setting | Type | Required | Accurate processing |
|---|---|---|---|
| serial | string | Yes | The value is converted to a string and then the spaces at the beginning and end are deleted. The remaining search is exact and case-sensitive, so the number must match exactly serialNumber in StageReturn. |
Response when a repair immobilizes the equipment
JSON — HTTP 200
{
"success": true,
"serial": "SN-123456",
"erpImmobilized": true,
"erpImmobilizationEnabled": true,
"erpProvider": "rentman",
"erpSyncStatus": "synced",
"erpStatusReason": "repair_open",
"stockAvailable": false,
"reason": "repair_open",
"repairStatus": "in_progress",
"repairId": "abc123",
"repairTitle": "Projector LED",
"problemDescription": "The projector no longer turns ons.",
"projectId": "project123",
"projectName": "Summer concert",
"projectNumber": "PRJ-00124",
"repairCreatedAt": "2026-07-10T09:18:22.000Z",
"repairUpdatedAt": "2026-07-11T14:52:03.000Z",
"updatedAt": "2026-07-12T14:00:00.000Z"
}
Response when no open repair is found
JSON — HTTP 200
{
"success": true,
"serial": "SN-INCONNU",
"erpImmobilized": false,
"erpImmobilizationEnabled": false,
"erpProvider": null,
"erpSyncStatus": null,
"erpStatusReason": "none",
"stockAvailable": true,
"reason": "none",
"repairStatus": null,
"repairId": null,
"repairTitle": null,
"problemDescription": null,
"projectId": null,
"projectName": null,
"projectNumber": null,
"repairCreatedAt": null,
"repairUpdatedAt": null,
"updatedAt": "2026-07-12T14:00:00.000Z"
}
This endpoint does not check the existence of an equipment in a catalog. Therefore, a number without an open repair also returns HTTP 200 with stockAvailable: true and the repair fields to null.
Returned fields
| Field | Type | Accurate value |
|---|---|---|
| success | boolean | Always true for an HTTP 200 response. |
| serial | string | Serial number received after deleting start and end spaces. |
| erpImmobilized | boolean | true when an open repair immobilizes the equipment. Compatible old repairs can also be taken into account. |
| erpImmobilizationEnabled | boolean | true if at least one open repair activates the ERP immobilization. Compatible old repairs can also be taken into account. |
| erpProvider | string | null | ERP supplier for the selected repair. If the immobilized repair does not contain this value, the API can keep that of the first open repair found. The connector currently produced by StageReturn uses rentman. |
| erpSyncStatus | string | null | ERP status of the repair selected. If the immobilized repair does not contain this value, the API can keep that of the first open repair found. The values returned by the API are detailed below. |
| erpStatusReason | string | none, erp_immobilization_disabled_or_pending, or the reason recorded on the immobilized repair. The default value for an immobilization is repair_open. |
| stockAvailable | boolean | false only when an open repair is considered to be immobilised; otherwise true. |
| reason | string | none without an open repair, repair_open for an open repair that is not fixed, or the reason recorded on the fixed repair. |
| repairStatus | string | null | todo, in_progress or null. |
| repairId | string | null | Identifier of the selected open repair. |
| repairTitle | string | null | First non-empty value found among the title, name or equipment name of the selected repair. If the immobilized repair does not provide any value, the API can retain that of the first open repair found. |
| problemDescription | string | null | First non-empty description found among the problem, diagnostic, description or remark fields of the selected repair. If the immobilized repair does not provide any value, the API can retain that of the first open repair found. |
| projectId | string | null | Identifier of the project associated with the selected repair when registered. If the immobilized repair does not provide an identifier, the API can keep the one of the first open repair found. |
| projectName | string | null | Name of the project associated with the selected repair when available. It can be completed from the linked project or kept since the first open repair found. |
| projectNumber | string | null | Number of the project associated with the selected repair when available. It can be completed from the linked project or kept since the first open repair found. |
| repairCreatedAt | string | null | Creation date of the retained repair converted to ISO 8601 format. If the immobilized repair does not provide any usable date, the API can keep the one of the first open repair found. |
| repairUpdatedAt | string | null | First available date among the selected repair update, ERP update, or last ERP synchronization, converted to ISO 8601. If no date is available for the fixed repair, the API can keep the one of the first open repair found. |
| updatedAt | string | Date the ISO 8601 format response was generated. |
GET
/missingEquipmentStatusApi?projectId=…&defectId=…
Consult a missing equipment
Returns the declaration designated by a project identifier and a defect identifier, provided it belongs to the company associated with the API key.
Query parameters
| Setting | Type | Required | Accurate processing |
|---|---|---|---|
| projectId | string | Yes | Exact identifier of the project. The start and end spaces are deleted. |
| defectId | string | Yes | The exact identifier of the declaration in the project. The start and end spaces are deleted. |
Request example
HTTP
GET /missingEquipmentStatusApi?projectId=project123&defectId=defect456 x-api-key: YOUR_API_KEY Accept: application/json
Example of a complete response
JSON — HTTP 200
{
"success": true,
"projectId": "project123",
"defectId": "defect456",
"equipmentName": "Cable XLR 10 m",
"isSerialized": false,
"serial": null,
"isMissingEquipment": true,
"missingQuantity": 5,
"returnedQuantity": 2,
"remainingMissingQuantity": 3,
"erpStockSyncEnabled": true,
"erpStockSynced": true,
"erpProvider": "rentman",
"erpConnectionId": "connection123",
"erpMappingId": "mapping123",
"erpItemId": "742",
"erpExternalItemId": "742",
"erpItemName": "Cable XLR 10 m",
"erpSyncStatus": "reintegrated",
"erpLastSyncAt": "2026-07-12T10:30:00.000Z",
"erpLastError": null,
"erpQuantityRemoved": 5,
"erpQuantityReintegrated": 2,
"erpRemainingQuantity": 3,
"projectName": "Summer festival",
"projectNumber": "PRJ-00130",
"entrepotId": "warehouse123",
"updatedAt": "2026-07-12T14:00:00.000Z"
}
Returned fields
| Field | Type exact | Accurate value |
|---|---|---|
| success | boolean | Always true for an HTTP 200 response. |
| projectId | string | Identifier of the project received after deleting the start and end spaces. |
| defectId | string | Report identifier received after deleting the start and end spaces. |
| equipmentName | string | null | Equipment name, or null s’il est vide. |
| isSerialized | boolean | true if the declaration contains a non-blank serial number in numeroSerie. |
| serial | string | null | Serial number of the declaration, after deletion of start and end spaces, or null. |
| isMissingEquipment | boolean | true only if equipementManquant is strictly value true. |
| missingQuantity | integer | value of quantite converted to a truncated integer. An absent or invalid value becomes 0. |
| returnedQuantity | integer | value of returnedQty converted to a truncated integer. A missing or invalid value becomes 0. |
| remainingMissingQuantity | integer | max(0, missingQuantity – returnedQuantity). |
| erpStockSyncEnabled | boolean | true only if the option is strictly set to true. |
| erpStockSynced | boolean | true only if the registered field is strictly true. |
| erpProvider | valeur JSON | null | ERP value saved, returned as is, or null. In the current StageReturn usage, this value is normally a string like rentman. |
| erpConnectionId | valeur JSON | null | ERP connection identifier saved, returned as is, or null. In current StageReturn usage, this value is normally a string. |
| erpMappingId | valeur JSON | null | ERP mapping identifier saved, returned as is, or null. In current StageReturn usage, this value is normally a string. |
| erpItemId | string | number | null | erpItemIdor erpExternalItemIdor null. The backend doesn’t force this string field. |
| erpExternalItemId | string | number | null | erpExternalItemIdor erpItemIdor null. The backend doesn’t force this string field. |
| erpItemName | valeur JSON | null | ERP article name saved, returned as is, or null. In current StageReturn usage, this value is normally a string. |
| erpSyncStatus | string | null | Registered ERP status. The values returned by the API are detailed below. |
| erpLastSyncAt | string | null | Date converted to ISO 8601 format, or null. |
| erpLastError | string | null | Last ERP error recorded, or null. This field may contain a variable technical error. |
| erpQuantityRemoved | integer | Quantity removed, converted to truncated integer; invalid or missing value: 0. |
| erpQuantityReintegrated | integer | Quantity reintegrated, converted to a truncated integer; invalid or missing value: 0. |
| erpRemainingQuantity | integer | value stored in erpRemainingQuantity, converted to truncated integer; invalid or missing value: 0. |
| projectName | string | null | Project name, or null. |
| projectNumber | string | null | Project number, or null. |
| entrepotId | string | number | null | Identifier of the filing of the declaration, if not that of the project, otherwise null. The backend doesn’t force this string field. |
| updatedAt | string | Date the ISO 8601 format response was generated. |
Values returned by the API
repairStatus
- todo : open repair to do.
- in_progress : open repair in progress.
- null : no open repair selected.
erpSyncStatus of a serialized repair
- syncing
- not_required
- not_configured
- rate_limited
- not_found
- error
- synced
- released
- null
erpSyncStatus of a missing equipment
- syncing
- not_configured
- rate_limited
- error
- synced
- reintegrated
- null
These lists include the values produced by the current API operation. An older piece of data can exceptionally contain a legacy value.
Codes HTTP réellement utilisés
| Code | Endpoint | Exact case |
|---|---|---|
| 200 | both | Request processed successfully. For equipmentStatusApi, HTTP 200 is also returned when no open repair matches the serial number. |
| 400 | equipmentStatusApi | Setting serial absent or empty. |
| 400 | missingEquipmentStatusApi | projectId or defectId absent or empty. |
| 401 | both | Missing or invalid API key. |
| 403 | both | API Configuration found but deactivated. |
| 404 | missingEquipmentStatusApi | Project or declaration not found, or resource not owned by the API key company. |
| 405 | both | Different HTTP method from GET. |
| 500 | both | Invalid API configuration or unexpected internal error. |
Exact Error Answers
All errors in these two endpoints are returned as:
JSON
{
"success": false,
"error": "error_code"
}
| value of error | HTTP | Endpoint | Meaning |
|---|---|---|---|
| method_not_allowed | 405 | both | The method used is not GET. |
| missing_api_key | 401 | both | Header x-api-key is absent or empty. |
| invalid_api_key | 401 | both | No API configuration matches the key. |
| api_disabled | 403 | both | The key exists, but API access is not enabled. |
| missing_serial | 400 | equipmentStatusApi | Parameter serial is absent or empty. |
| missing_parameters | 400 | missingEquipmentStatusApi | projectId or defectId is absent or empty. |
| project_not_found | 404 | missingEquipmentStatusApi | The project does not exist or is not owned by the API key company. |
| equipment_not_found | 404 | missingEquipmentStatusApi | The declaration does not exist or is not owned by the API key company. |
| invalid_enterprise_ref | 500 | both | The API configuration is invalid. Customer must contact StageReturn support. |
| internal_error | 500 | both | An unexpected error occurred during processing. |
Integration rules to be followed
Serialized Availability
Use stockAvailable as the primary outcome. erpImmobilized indicates the ERP cause of the unavailability.
Unknown number
equipmentStatusApi does not have a response 404. An available response does not confirm that the number exists in a catalog.
Missing Credentials
To call missingEquipmentStatusApi, the integration must already know the projectId and the defectId. There are no current public endpoints that allow you to search for or list them.
Null values
Treat all fields marked | null as truly optional.
Encoding of settings
Always encode parameters with URL encoding, including serial numbers containing spaces or special characters.
Error handling
Base the logic on the HTTP code and the field value error. Do not attempt to interpret text from another source.
With public endpoints available, an external integration can view a status by serial number and view a statement known by its two identifiers. It can’t list projects, search for statements, create an incident, or edit data.
Checklist before production
- The API key is stored only on the server side.
- Parameters are encoded in the URL.
- The client processes HTTP codes before using the data.
- The fields that can be applied null are being addressed.
- The status of a serialized equipment is based on stockAvailable.
- An HTTP 200 response of equipmentStatusApi is not used as proof of existence in a catalog.
- Credential projectId and defectId are preserved when the integration needs to consult a missing equipment.
- Errors 500 are logged without saving the API key.
Technical support
In case of failure, forward to support the called endpoint, the parameters used without sensitive data, the HTTP code, and the field value of the error. Never pass your API key.
