API

The ActiveManage REST API exposes the platform's data and actions to scripts, integrations, mobile apps and other services. If a feature is available in the UI, there's almost always an API equivalent — and the API is the right surface for everything that's not a manual click.

What the API Provides

• CRUD on every datastore — list, create, read, update, delete records.
• Authentication — sign users in, refresh tokens, sign out.
• Search — full-text, faceted and filtered queries.
• Workflow actions — trigger business actions (submit form, approve record, send email).
• File upload/download — manage attachments and the file store.
• Admin operations — create users, modify groups, configure tenants (restricted to admin tokens).
• Webhooks — register URLs to be called on events.

Conventions

• REST: GET retrieves, POST creates, PATCH updates, DELETE removes.
• JSON in / JSON out: application/json for both directions.
• Cursor pagination: list endpoints return { data: [...], nextCursor: 'abc' }.
• ISO-8601 dates: in UTC unless explicitly timezoned.
• Versioning: /api/v1/…. Breaking changes increment the version; current is v1.

Typical Use Cases

• Mobile app: Native iOS/Android consumes the API for everything users do.
• Salesforce integration: Nightly sync of customers and orders.
• Data warehouse: Pull all records into BigQuery for analytics.
• Slack notifications: Webhook fires on order creation, posts to a channel.
• Custom scripts: Bulk import, batch delete, scheduled cleanups.

The API supports two authentication models: API keys for service-to-service calls and user tokens for end-user actions. This article focuses on API keys.

Creating a Key

1. Open Architect Panel → API → Keys and click New Key.
2. Friendly name — descriptive (e.g. “Salesforce nightly sync”).
3. Scopes — pick the least-privilege set this key needs (e.g. read+write on a specific datastore, no admin).
4. Optional restrictions:
   • Allowed source IPs — restrict to your integration server's CIDR.
   • Allowed endpoints — whitelist paths the key can hit.
   • Expiry date — force rotation after N days.
5. Generate. The key is shown once. Copy it into your secrets manager immediately.

Using the Key

Include the key in the Authorization header:

Authorization: Bearer am_live_xxxxxxxxxxxxxxxxxxxx

Best Practices

• One key per integration. Easier to rotate, easier to revoke.
• Least privilege. Reads-only key for a reporting integration, not a write key.
• IP allowlist. If the integration server has a fixed IP, lock the key to it.
• Rotate annually. Set expiry to force a rotation reminder.
• Never embed in client-side code. Keys in browser JS or mobile binaries are extractable.

Worked Examples

• Salesforce sync: Read+write on Customers, Orders. IP-locked to Salesforce's static egress. Expires in 1 year.
• Internal reporting: Read-only across all datastores. No IP lock (runs from BI tools). Expires in 90 days.
• Slack notifier: No read scope; webhook-only. Restricted to /api/notifications/slack endpoint.
• Mobile backend: Backend proxies user actions; mobile app uses user tokens, backend uses an admin-scoped service key.

Every entity and action in ActiveManage is reachable through a REST endpoint. This article gives an overview of the endpoint families and links to per-family detail pages.

Endpoint Families

• /auth/* — sign in, refresh tokens, sign out, MFA challenges, password reset.
• /users/* — user CRUD, profile updates, preferences, password change.
• /tables/* — datastore management, schema introspection.
• /records/{table}/* — records inside a datastore (list, get, create, update, delete).
• /files/* — upload, download, list, delete file store attachments.
• /workflows/* — trigger named workflows (custom business actions).
• /webhooks/* — manage outbound webhook subscriptions.
• /notifications/* — send and receive notification events.
• /admin/* — tenant, group, permission, billing admin (requires admin scope).
• /search/* — full-text and structured search.

Common Endpoint Patterns

• GET /records/orders — list orders.
• GET /records/orders/{id} — get one order.
• POST /records/orders — create.
• PATCH /records/orders/{id} — partial update.
• DELETE /records/orders/{id} — soft delete.
• POST /workflows/orders/{id}/approve — run a workflow action.

Discovering the Schema

Hit GET /tables/{name} to introspect the columns, types and validation rules of any datastore. This lets dynamic clients adapt to schema changes without redeploying.

OpenAPI

A complete OpenAPI 3 spec is available at /api/openapi.json. Use it to generate client SDKs in any language — TypeScript, Python, Go, C#, Ruby.

API rate limits protect the platform from accidental floods and abusive scripts. Limits are applied per API key (or per user token), per endpoint family, in a sliding window.

Default Limits

• Per IP, unauthenticated: 30 requests/minute.
• Per user token: 300 requests/minute.
• Per service key, default scope: 1000 requests/minute.
• Per service key, with elevated tier: 10,000 requests/minute.
• Per service key, write endpoints: 100 writes/minute.
• Per service key, bulk import endpoints: 5 bulk operations/minute.

Headers

Every response includes three headers:

• X-RateLimit-Limit — total allowed in the current window.
• X-RateLimit-Remaining — how many you have left.
• X-RateLimit-Reset — Unix epoch when the window resets.

When you exceed the limit, you get HTTP 429 with a Retry-After header. Back off and retry then.

Tuning for Your Workload

• Read-heavy: Default 1000/min is generous; rare to hit.
• Bulk imports: Use the bulk endpoints; one bulk request can carry 1000 records.
• Real-time mirroring: Request elevated tier and stagger writes — 100 writes/min ≈ 1.67/sec.
• Webhook-driven: Almost never hits limits — events drive your calls.

Worked Examples

• Nightly sync: 200,000 records pulled via 200 paginated requests. At 1000/min that's 12 seconds — well within limits.
• Live mirror: Mirror Salesforce to ActiveManage on every change. Write traffic ~50/hour — far below.
• Bulk migration: Import 1M records via 1000 bulk requests of 1000 records each. At 5 bulk/min that's 200 minutes — schedule overnight.

Tip: If you regularly bump the limit, you're probably building wrong — consider webhooks (push, not pull) or bulk endpoints instead of single-record calls.