Getting started with the REST API

The integration API lets external systems write into UniAsset — creating assets, updating assignments, recording maintenance, pushing positions, and ingesting telemetry.

Requirements

• Available on: Odyssey, Cosmos
• Roles: Owner, to create the API key

Before you start

1. Confirm your organization is on Odyssey or above.
2. Create an API key with the minimum scopes you need. Store it — it is shown once.
3. Create the categories, locations, and statuses your data will reference. The API resolves names against your organization; it does not create them.

Authentication

Send the key as a bearer token:

POST /api/integrations/assets/create
Authorization: Bearer ua_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

The organization is derived server-side from the key. It is never read from the request body, the URL, or a header — so there is no way to act on another organization's data.

The endpoints

The full field reference, with payload examples, is in-product at Settings → Integrations → Developer Guide.

Names are resolved, not created

Category, location, and status names in a request are matched against records that already exist in your organization. An unmatched name returns 404.

This is deliberate. Silently creating categories from a typo in an upstream system produces an unusable taxonomy within weeks.

Assignment targets People

Assigning by email resolves the user, then their Person record. Assignments target people, not accounts — which is what lets custody survive someone leaving. See People vs users.

Geo position is not location

Geo position is a physical coordinate. Location is an organizational place in your hierarchy.

Sending coordinates does not change which building an asset belongs to. They answer different questions and are stored separately.

Errors

Every error returns the same shape, with a stable machine-readable code.

Branch on code, not on the message text. Codes are stable; messages may be reworded.

Rate limits

Configured per key, 1–1000 requests per minute, default 60. Payloads are capped at 1 MB.

Watch the activity log

Settings → Integrations → Activity records every request: endpoint, key, IP, status code, timestamp, and a sanitised body.

Failed requests are logged as faithfully as successful ones. While going live, this is the fastest way to see what the server actually received rather than what you believe you sent.

Versioning

Endpoints are currently unversioned and treated as v1.

Adding optional request fields, response fields, endpoints, or webhook events can happen at any time — build defensively: ignore unknown response fields rather than failing on them, and do not depend on field ordering.

Breaking changes will get a version prefix, with Deprecation and Sunset headers and a minimum 90-day window.

Common mistakes

Sending a category name that does not exist yet. Create it in UniAsset first.

Parsing error messages instead of codes. Codes are the stable contract.

Sending coordinates expecting the asset to move location. Those are different fields.

Not checking the activity log when something breaks. It usually contains the answer.

Troubleshooting

Everything returns 403 PLAN_UPGRADE_REQUIRED. Your plan does not include API access. Odyssey or above is required.

403 FORBIDDEN on one endpoint only. The key lacks that endpoint's scope.

404 on a request that looks correct. A referenced asset, user, location, or category does not exist in your organization. Names are matched exactly.

422 VALIDATION_ERROR. The payload failed validation. The response says which field.

IoT ingestion fails while other endpoints work. IoT is gated separately — the key needs iot:signal:ingest and your plan needs IoT access.

Related articles

• How to create API keys
• How to use webhooks
• Integrations overview
• Understanding IoT signals
• Geo-position tracking
• API security