Connect your own systems with the API

With the Beam API you read and maintain items, locations and stock from your own systems, and create and follow orders and tasks. The API is meant for integrations that run on a server.

Before you start

• You need administrator permissions on the organisation. If you don’t have them, ask your organisation administrator for access.
• An API key belongs to one organisation and can only reach that organisation.

Create an API key

1. Open the settings menu and choose Organization settings.
2. Choose API keys, then New API key. If your last sign-in was too long ago, Beam asks you to sign in again first.
3. Enter a Name, choose what your integration needs under Access, and choose 30, 90, 180 or 365 days under Valid for.
4. Choose Generate key.
5. Beam shows Save this key now. Copy the key with Copy and put it in your server’s secret store. Also note the Organization path: you use it in every request.
6. Confirm that you understand the value cannot be recovered and choose I saved the key.

Beam shows the full key only once. If you lose it, Rotate gives you a new value.

Which access should you choose?

Choose the least access your integration needs. Each endpoint in the API reference lists the access levels it accepts.

Access	What the key can do
Read only	Read items, locations, stock and orders.
Inventory sync	Read items and locations, and read and change stock.
Order sync	Read items, locations and stock, read and change orders, and manage tasks.
Full API access	All operations in the API reference, including creating and updating items and locations.

Reading tasks requires Order sync or Full API access. Read only does not include tasks. Order sync lets you read inventory but not change it.

Make your first request

Send the key with every request in the Authorization header. Replace YOUR_ORGANIZATION_ID with the ID from your organisation path.

curl 'https://connect.beamtracking.com/v1/organizations/YOUR_ORGANIZATION_ID/locations' \
  -H "Authorization: Bearer <your API key>"

A successful response contains an items array of locations. Save the relevant locationId for inventory, order and task requests. If no locations are returned, the array is empty.

Never put a key in a website or mobile app. The API only works from a server: a browser page cannot call it directly.

The API reference

The API reference describes the available endpoints, fields, error handling and limits. To load the API into Postman or a code generator, use the OpenAPI file.

Update records reliably

• Send a new UUID in Idempotency-Key for each write. After a timeout, retry the same request with the same key to avoid duplicate changes.
• For updates requiring If-Match, send the record’s latest ETag. If there is a conflict, read the record again before submitting a new change.
• A stock correction sets the total quantity. Use an inventory movement when goods physically move to another location.
• Send the complete desired order plan when updating an order. Omitting an unexecuted line cancels it.
• An accepted change may still be processing. Follow the background-processing guidance in the API reference and check the resulting records.

Manage a key

Tap a key under Existing keys.

• Rotate issues a new value with the same lifetime. The current key stops immediately, so update your integration right away.
• Disable stops access from the next request. After Enable, a previously refused key can take up to five minutes to work again.
• Revoke permanently cannot be undone.

A key stops working after its expiry date. The app warns you 30 days ahead.