# Get the general-ledger mapping

> The exports.gl_mapping.get operation: GET /api/v1/exports/gl_mapping in the REST API and the exports_gl_mapping_get tool in the MCP server.

Returns the legal entity's general-ledger mapping in the mode of the request: the rules that map Ownrecord
ledger accounts to the entity's own chart of accounts in the accounting export's journal. A rule's `account` is
an account kind (e.g. `tax_payable`), an account code, or a code prefix ending in `*`; for each account the
exact code wins, then the longest prefix, then the kind. With no mapping (`version` 0), the journal's
general-ledger columns stay empty.

## At a glance

- **REST:** `GET /api/v1/exports/gl_mapping`
- **MCP tool:** `exports_gl_mapping_get`
- **Operation ID:** `exports.gl_mapping.get`
- **Scope:** Legal entity
- **Permission:** `ledger:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `ledger:read` scope
- **Since:** M8

## Request

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field               | Type              | Description                                                                            |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------- |
| `object`            | `"gl_mapping"`    |                                                                                        |
| `entityId`          | `ent_…` ID        |                                                                                        |
| `livemode`          | boolean           |                                                                                        |
| `rules`             | array of object   |                                                                                        |
| `rules[].account`   | string            | An account kind (e.g. `tax_payable`), an account code, or a code prefix ending in `*`. |
| `rules[].glAccount` | string            | The account in the entity's own chart of accounts.                                     |
| `rules[].glName`    | string or null    |                                                                                        |
| `version`           | integer           | 0 while no mapping is set; pass it as `expectedVersion` when you change it.            |
| `updatedAt`         | date-time or null |                                                                                        |
| `updatedBy`         | string or null    |                                                                                        |

## Examples

### A mapping to a German chart (SKR03-style codes)

```http
GET /api/v1/exports/gl_mapping
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "gl_mapping",
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47zm",
  "livemode": false,
  "rules": [
    {
      "account": "processor_clearing",
      "glAccount": "1360",
      "glName": "Stripe clearing"
    },
    {
      "account": "bank",
      "glAccount": "1200",
      "glName": "Bank"
    },
    {
      "account": "tax_payable",
      "glAccount": "1776",
      "glName": "VAT payable"
    },
    {
      "account": "tax_payable:EU_OSS_UNION:*",
      "glAccount": "1777",
      "glName": "OSS VAT payable"
    },
    {
      "account": "revenue",
      "glAccount": "8400",
      "glName": "Revenue"
    },
    {
      "account": "processor_fees",
      "glAccount": "4970",
      "glName": "Payment fees"
    }
  ],
  "version": 3,
  "updatedAt": "2026-10-01T09:00:00.000Z",
  "updatedBy": "usr_01m4tx5nj8emwbyf7y9vcf47zk"
}
```

## Errors

| Code                                                                                         | HTTP status | When                                                                                                                     | What to do                                                                                                                                         |
| -------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required)             | 400         | The request names no legal entity (an org key without `Ownrecord-Entity`, or a brand key: exports belong to the entity). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)       | 403         | You can't read this entity's ledger (`ledger:read`; brand-scoped members never see it).                                  | Ask an organization owner or admin for a role or scope that allows this action.                                                                    |
| [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403         | You have no live-mode access, so you can't use live exports.                                                             | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.                        |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).