Skip to main content
POST
Move Transport Routes
Move transport routes to another organization of your group: the header organization or one of its accepted, enabled descendant organizations. Each route moves as with the organization_id of Update Transport Route Attachment or Organization: it keeps its id, its sections (ids and distances), the file it was read from, its custom-column values and its history; the emissions of its sections are re-attributed to the target at once, and its sections are recalculated there (status: pending until then) with the target’s default emission factor database, GWP and country. Two endpoints, one contract:
  • POST /v1/transports/move takes the routes’ ids, at most 1,000.
  • POST /v1/transports/move-by-filters takes the query parameters of List Transport Routes and the filter_hash that list answered, and moves every route it matches, with no limit. A filter_hash that no longer matches the parameters answers 409, so the move reaches exactly the routes the list showed.
Everything the routes carry is checked against the target before anything is written: when one route cannot move (409, 422), none moves. Then the routes are written in batches of 500, each committed, and their sections are queued for recalculation. Routes the target already owns are left alone, so sending the same request again after a failure finishes the move; those of them still pending are queued for recalculation again, in case the failure came between writing a batch and queuing it.

Request

Headers

string
required
A user session. An API key without a user is refused (403): a move writes into another organization.
string
required
The header organization. You need a non-Viewer membership in it.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters (/move-by-filters)

The filters of List Transport Routes, exactly as sent to it, including consolidate_group, organization_id[] and the column filters (filter_by, filter_match, filter_or_fields).

Body

string
required
The organization the routes move to.Example: "a8315ef3-dd50-43f8-b7ce-d839e68d51fb"
string[]
/move only, required: the routes to move, 1 to 1,000.
boolean
default:"false"
/move only: let the routes belong to the header organization’s descendants. Without it only the header organization’s own routes are found.
string
/move-by-filters only, required: the filter_hash of the list page.

Response

HTTP 200 once every route is written. While it runs, its progress is kept on a BULK_MOVE processing job (items_success out of items_total).
string
The organization the routes moved to.
integer
Routes moved.
integer
Routes the organization already owned: nothing to do.
string[]
Requested routes that do not exist, or that the header organization may not write (a subsidiary’s route without consolidate_group, another company’s): not moved.
integer
Sections queued for recalculation in the target.
string | null
The BULK_MOVE processing job, or null when nothing changed owner.

Example

Response (200)

Common Errors

403 Forbidden

Cause: organization_id is not the header organization or one of its accepted, enabled descendants, or the caller may not write into it: an API key without a user (CROSS_ORG_WRITE_REQUIRES_USER), a Viewer, or no membership in the header organization.

409 Conflict

Cause: TRANSPORT_MOVE_CUSTOM_COLUMN_CONFLICT: a custom-column value of a route has a column of another type in the target organization, or points at data of its current organization. With /move-by-filters, also a filter_hash that no longer matches the parameters: list again and retry.

422 Unprocessable Entity

Cause: MULTIDB_CUSTOM_RECORD_NOT_FOUND_OR_DISABLED: a section uses a custom emission factor the target organization may not use (its database is private to another organization, or the record is disabled). Also a body that is not valid: more than 1,000 transport_ids, a field that is not a UUID, or an unknown field.