> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Move Transport Routes

> Move many transport routes, by id or by the list's filters, to another organization of the group

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](https://code.dcycle.io/api-reference/transport/update-attachment.md): 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](https://code.dcycle.io/api-reference/transport/list.md)
  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

**Authorization** `string` *required*

A user session. An API key without a user is refused (`403`): a move writes into another organization.

**x-organization-id** `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](https://code.dcycle.io/api-reference/transport/list.md), exactly as sent to it, including
`consolidate_group`, `organization_id[]` and the column filters (`filter_by`, `filter_match`, `filter_or_fields`).

### Body

**organization\_id** `string` *required*

The organization the routes move to.

**Example:** `"a8315ef3-dd50-43f8-b7ce-d839e68d51fb"`

**transport\_ids** `string[]`

`/move` only, required: the routes to move, 1 to 1,000.

**consolidate\_group** `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.

**filter\_hash** `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`).

**organization\_id** `string`

The organization the routes moved to.

**moved\_count** `integer`

Routes moved.

**unchanged\_count** `integer`

Routes the organization already owned: nothing to do.

**not\_found\_ids** `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.

**recalculating\_section\_count** `integer`

Sections queued for recalculation in the target.

**processing\_job\_id** `string | null`

The `BULK_MOVE` processing job, or `null` when nothing changed owner.

## Example

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.dcycle.io/v1/transports/move-by-filters?transport_direction=downstream&consolidate_group=true&organization_id[]=5ab8d102-2bd6-4642-a79f-519ee472f94f" \
  -H "Authorization: Bearer ${DCYCLE_TOKEN}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{"organization_id": "a056c9e7-6a6e-4361-a313-d029997ddd22", "filter_hash": "3f1c..."}'
```

```json Response (200) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "organization_id": "a056c9e7-6a6e-4361-a313-d029997ddd22",
  "moved_count": 26719,
  "unchanged_count": 0,
  "not_found_ids": [],
  "recalculating_section_count": 26719,
  "processing_job_id": "0b8f8a3e-27f5-4b8e-9d0e-2f3c1f6a9c11"
}
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.