Upload a spreadsheet of units
Editor and above, or an API key with the import scope (ADR-026). A CSV (UTF-8, UTF-16 or
Windows-1252; ;, ,, tab or | separated) or XLSX file of at most 10 MB, 10 000 rows and 200
columns; the first non-empty row holds the headers. The answer is the import with a mapping
proposed from the headers (registry CSV headers, aliases, labels; units such as (kWh) are
converted), or taken from the import preset named in preset (the ERP registry): a preset maps
the columns it knows by their headers and leaves the others unmapped.
A key stages the import only: members of the organisation commit it and approve its values in the portal, so declared data still enters through a member's decision.
apiKeyAuthorizationBearer <token>Organisation API key sent as Authorization: Bearer bp_live_… (ADR-017). Accepted only by the
operations that list this scheme, with the scope in their x-api-key-scope.
multipart/form-data- body
file*unknownpreset?ImportPresetIdAn import preset of the ERP registry (getErpRegistry, ADR-026): which column header of an ERP
export maps to which registry field.
^[a-z0-9]+(-[a-z0-9]+)*$length <= 60sheet?stringThe XLSX worksheet to read (the first one when omitted).
1 <= length <= 100The import.
application/json- response
Either created_by (a member uploaded the file) or created_by_api_key (an integration staged
it with an API key of scope import, ADR-026) is set.
approved_at?stringdate-timeapproved_by?stringuuidcommitted_at?stringdate-timecreated_at*stringdate-timecreated_by?created_by_api_key?An organisation API key (ADR-017) that reported an event (source api) or staged an import (ADR-026).
filename*stringformat*ImportFormat"csv""xlsx"headers*array<string>id*stringuuidmapping*array<>options*preset?ImportPresetIdAn import preset of the ERP registry (getErpRegistry, ADR-026): which column header of an ERP
export maps to which registry field.
^[a-z0-9]+(-[a-z0-9]+)*$length <= 60row_count*integerData rows (empty rows are left out).
row_version*RowVersionOptimistic-concurrency version; send it back as If-Match when updating.
int641 <= valuesample_rows*array<array<string>>The first data rows of the file as read (at most 5), to show example values while mapping.
sheet?stringThe XLSX worksheet that was read.
size_bytes*integerint64status*ImportStatusuploaded (mapping can change) → validating → validated → committing → committed;
failed when the file could not be validated (validate again). A changed mapping sends a
validated import back to uploaded.
"uploaded""validating""validated""committing""committed""failed"summary?updated_at*stringdate-timevalidated_at?stringdate-timecurl -X POST 'https://example.com/api/v1/imports' \ -F 'file=null'{ "approved_at": "2019-08-24T14:15:22Z", "approved_by": "02030314-b162-4b4d-8af1-88eabdcc615d", "committed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "created_by": { "display_name": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "created_by_api_key": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string" }, "filename": "string", "format": "csv", "headers": [ "string" ], "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mapping": [ { "auto": true, "column": 0, "header": "string", "target": "string", "unit": "string" } ], "options": { "battery_model_id": "6a002912-62a3-4058-99d0-53cbf87e9e1c", "facility_id": "82d24387-b696-4928-8926-f6f7f16d3353" }, "preset": "string", "row_count": 0, "row_version": 1, "sample_rows": [ [ "string" ] ], "sheet": "string", "size_bytes": 0, "status": "uploaded", "summary": { "approved": 0, "created": 0, "duplicates": 0, "errors": 0, "not_approved": 0, "rows": 0, "valid": 0, "warnings": 0 }, "updated_at": "2019-08-24T14:15:22Z", "validated_at": "2019-08-24T14:15:22Z"}The organisation's changes, oldest first, for polling GET
Any member, or an API key with the `read` scope (ADR-026). The organisation's changes in the order they became visible, oldest first, as `{id, occurred_at, entity_type, entity_id, action}`: no values, no actors, no personal data; read the entity for its current state. Keep `next_cursor` of the last page and ask again later: a change appears only once every transaction that started before it has finished, so a cursor never skips a change that commits late. `next_cursor` is set whenever the page has items, also on the last page; an empty page keeps the cursor you sent (`next_cursor` null). Without `cursor` the feed starts at the beginning of the organisation's history.
One import with its mapping and summary GET
Any member, or an API key with the `import` scope (ADR-026). Poll it after `validateImport`: the status becomes `validated` (or `failed`) and `summary` counts valid, warning, error and duplicate rows.