Skip to main content

Accounts API

The Accounts API is a REST API for the administration of one org. Use it from scripts and integrations, with a service-account credential, to:

  • list the buildings of an org,
  • set a building's gross area, and
  • set the gross area of many buildings of the org at once, as a background batch.

It is separate from the GraphQL API and authenticates differently: it takes a service-account credential made for one org, not a personal access token. See Authentication.

Where to start​

  1. Authentication: create a credential, get a token, find your account id and org id.
  2. Buildings: list the org's buildings and set one building's gross area.
  3. Batches: set the gross area of up to 1,000 buildings in one background batch.
  4. Errors and limits: every error code, the rate limits and how to retry.
  5. API reference: every route with its parameters, bodies and examples, generated from the OpenAPI contract. The contract itself is at https://api.mapped.com/v1/accounts/swagger.json.

Base URL and routes​

Every route is under https://api.mapped.com/v1/accounts/{accountId}/orgs/{orgId}, where orgId is the org your credential was made for and accountId is the account that holds that org.

RouteDoesGuideReference
GET /buildingsA page of the org's buildingsBuildingsList buildings
PUT /buildings/{buildingId}/gross-areaStart an update of one building (async)BuildingsSet gross area
POST /buildings/gross-area:batchStart a batch of the org's buildingsBatchesStart a batch
GET /batches/{batchId}A batch's status and per-item resultsBatchesBatch status

Any other path or verb under /v1/accounts/{accountId}/... answers 404 with the code not_found. The OpenAPI contract, /v1/accounts/swagger.json, is also served under the prefix and is public.

Conventions​

  • Bodies are JSON (Content-Type: application/json); any other content type is 400 bad_request. A body over 1,000,000 bytes is refused with 413.
  • A success is { "success": true, "data": ... }. A failure is { "success": false, "error": "...", "code": "..." } with the matching HTTP status. The code is stable and meant for programs; see Errors and limits.
  • Areas are in square feet.
  • Updates are asynchronous: setting one building's gross area (PUT) and a batch (POST) both answer 202 with a statusUrl to poll; the outcome is in the status's items.
  • Responses of the routes under /v1/accounts/{accountId}/... are never cached: they are for the caller only. The OpenAPI document at /v1/accounts/swagger.json is public and the one cacheable answer.