Create and Update Assets Through the BigWave API
The BigWave API could already read your assets. You could fetch one asset, list them by asset type or by customer, and ask which ones changed since a given date. Now it can write them too. Two new calls let your code create an asset and update an asset.
Here is where that helps:
- Your purchasing system buys a new air handler. It creates the asset in BigWave the day the unit arrives, at the right site.
- An inspection app collects serial numbers in the field. A script sends them to the matching assets in BigWave.
- You keep a master asset list in another system. A nightly job keeps BigWave’s asset register in step with it.
If you are still choosing a field service system, this matters too. Your asset records can move into and out of BigWave through code, and nobody has to retype them.
Before you start
Both calls live at /api/v1/Asset, next to the GET calls you may already use. Every call needs a Bearer token. Get one from POST /api/auth/RequestToken with your API key’s token and secret. Then send it on each call:
Authorization: Bearer <your token>Create an asset
POST /api/v1/Asset creates one asset. Four values are required:
assetTypeName: the asset type, by name.clientAssetId: your ID for the asset. It must be new within that asset type.clientCustomerId: the customer’s ID. Your own customer ID works, and so does BigWave’s.clientSiteId: the site, within that customer. The asset starts at this site.
The rest are optional: assetName, statusName, make, manufacturer, model, notes, serialNumber, acquisitionDate, inServiceDate and customFieldValues. Leave out the name, and the asset takes its clientAssetId as its name. Leave out the status, and it gets the asset type’s first status.
POST /api/v1/Asset
Authorization: Bearer <your token>
Content-Type: application/json
{
"assetTypeName": "Air Handlers",
"clientAssetId": "AHU-104",
"clientCustomerId": "ACME",
"clientSiteId": "Plant 1",
"assetName": "Roof unit 4",
"manufacturer": "Example Air Co.",
"serialNumber": "SN-48213",
"inServiceDate": "2027-01-15",
"customFieldValues": [
{ "id": 1234, "value": "Quarterly" }
]
}A good create gets 201 Created. The Location header holds the new asset’s address. The body holds the new asset, in the same shape GET returns. Here it is, cut short:
{
"assetId": 5001,
"assetName": "Roof unit 4",
"assetTypeName": "Air Handlers",
"clientAssetId": "AHU-104",
"clientCustomerID": "ACME",
"clientSiteID": "Plant 1",
"statusName": "Active",
"serialNumber": "SN-48213",
...
}Keep the assetId. It is BigWave’s ID for the asset, and the update call needs it.
Update an asset
PUT /api/v1/Asset/{id} changes one asset, where {id} is BigWave’s asset ID. Send only the values you want to change. Anything you leave out stays as it is.
You can change clientAssetId, assetName, statusName, make, manufacturer, model, notes, serialNumber, acquisitionDate, inServiceDate and custom fields. A new clientAssetId must still be unique within the asset type. The status must be one of the asset type’s statuses, or the call is refused. This call does not change the asset type or where the asset sits.
PUT /api/v1/Asset/5001
Authorization: Bearer <your token>
Content-Type: application/json
{
"serialNumber": "SN-48213-R",
"statusName": "Broken",
"customFieldValues": [
{ "id": 1234, "value": "Monthly" },
{ "id": 1235, "value": "" }
]
}That body changes the serial number and the status, sets one custom field and clears another. The answer is 200 OK, with the whole asset as it stands after the change.
An update also shows in the “changed since” call, even when you changed only custom fields. A job that polls that call picks up your own writes.
Custom fields
Custom fields go in customFieldValues, as a list of id and value pairs. Use the field IDs exactly as GET returns them in an asset’s customFieldValues. To find them, GET one asset of the same type and look.
- An empty value clears the field.
- Dates go in as text, such as
2027-01-15. - A dropdown field takes one of its listed choices.
- BigWave refuses an ID that does not belong to the asset’s type.
- A field you leave out of the list stays as it is.
Safe to run again
Scripts stop halfway. Connections drop. Two rules make a second try safe.
First, BigWave refuses a create when another asset of that type already has the same clientAssetId. Say your script sends a create, the connection drops before the answer comes back, and the script tries again. The second try gets an error, and BigWave still holds one asset.
Second, each call saves everything or nothing. On a create, the asset, its starting site and its custom fields save together. If one part fails, BigWave saves none of it.
An update sets values. Send the same update twice and the asset ends up the same as if you sent it once.
When something is wrong
Bad input gets 422 Unprocessable Entity, and BigWave saves nothing. The body is a plain message that says what is wrong, one line per problem:
No site with ClientSiteId 'Plant 9' exists for customer 'ACME'.
Another asset of this asset type already has the ClientAssetId 'AHU-104'.Your script can log that message as it is, and a person can read it and fix the data. An update to an asset that does not exist gets 404 Not Found.
Partner keys
A partner API key can use both calls, but only for the customers the partner is authorized for. It cannot reach another customer’s assets. An update to one of those assets gets 404, the same answer as for an asset that does not exist. A create at one of those customers gets 422 with “No customer … exists”.
Who changed what
Every change made through the API shows in the asset’s audit history with the source “API”. For a partner key, the source also names the partner. Your office can see which changes came from another system.
Limits
- Each call handles one asset. A script that changes 500 assets makes 500 calls.
- Nothing here deletes an asset.
- You set up asset types, their statuses and their custom fields in BigWave itself.
The BigWave API documentation page (the Swagger page) lists every field for both calls, with each response code. If you need an API key, contact BigWave support.