> ## Documentation Index > Fetch the complete documentation index at: https://docs.slash.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or replace an accounting mapping > Automatically code one dimension for everything from a source, such as a card or merchant. Replaces any existing mapping for the same source and dimension. Set `applyToExistingEntries` to also recode entries still in review. On platforms that keep account mappings per subsidiary, such as NetSuite, an `account` mapping for an `account` or `accounts_payable` source applies to the connection's default subsidiary; every other mapping applies to the whole connection. ## OpenAPI ````yaml /openapi-v2.json put /v2/accounting/mappings openapi: 3.1.0 info: title: Slash Public API V2 description: >- Send money for a Slash legal entity. Every request uses an API key. Transfer creation returns a Transfer that links its resulting transactions. version: 0.0.1 servers: - url: https://api.slash.com description: production security: - api_key: [] paths: /v2/accounting/mappings: parameters: - name: x-legal-entity in: header required: true description: >- The legal entity to act on. Required on every request; a user API key can act on any legal entity its user has access to. schema: type: string pattern: ^le_[a-zA-Z0-9]+$ put: summary: Create or replace an accounting mapping description: >- Automatically code one dimension for everything from a source, such as a card or merchant. Replaces any existing mapping for the same source and dimension. Set `applyToExistingEntries` to also recode entries still in review. On platforms that keep account mappings per subsidiary, such as NetSuite, an `account` mapping for an `account` or `accounts_payable` source applies to the connection's default subsidiary; every other mapping applies to the whole connection. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/accounting-mapping-upsert' example: source: type: merchant id: merchant_v2_2rj4l7hmrrrcv dimensionKey: account valueId: accounting_account_2rj4l7hmrrrcv applyToExistingEntries: true responses: '200': description: The mapping as stored. content: application/json: schema: $ref: '#/components/schemas/accounting-mapping' example: id: accounting_mapping_2rj4l7hmrrrcv connectionId: accounting_connection_2rj4l7hmrrrcv source: type: merchant id: merchant_v2_2rj4l7hmrrrcv dimensionKey: account valueId: accounting_account_2rj4l7hmrrrcv createdBy: user createdAt: '2026-09-18T20:11:02.000Z' '400': $ref: '#/components/responses/PublicApiV2Error400AccountingMappingsUpsert' '401': $ref: '#/components/responses/PublicApiV2Error401Unauthorized' '403': $ref: >- #/components/responses/PublicApiV2Error403ForbiddenForbiddenLegalEntityNotAvailableUserApiKeyRequired '404': $ref: '#/components/responses/PublicApiV2Error404AccountingMappingsUpsert' '409': $ref: '#/components/responses/PublicApiV2Error409DefaultSubsidiaryRequired' '429': $ref: '#/components/responses/PublicApiV2RateLimited' '500': $ref: '#/components/responses/PublicApiV2Error500Internal' security: - api_key: [] components: schemas: accounting-mapping-upsert: title: AccountingMappingUpsert description: >- Create or replace the mapping of one source for one dimension. Exactly one of `valueId` (platform and generic dimensions) or `customFieldValue` (custom-field dimensions) is required. type: object properties: connectionId: type: string description: >- The connection to write to. Optional when the legal entity has exactly one connection; required when it has several. example: accounting_connection_2rj4l7hmrrrcv source: $ref: '#/components/schemas/accounting-mapping-source' dimensionKey: type: string minLength: 1 maxLength: 255 description: >- The dimension to code, a `key` from `GET /v2/accounting/dimensions` that is `enabled` and `mappable` on the connection. example: account valueId: type: string minLength: 1 maxLength: 255 description: >- An enabled value of that dimension, from `GET /v2/accounting/dimensions/{dimensionKey}/values`. Not accepted for custom-field dimensions. example: accounting_account_2rj4l7hmrrrcv customFieldValue: description: >- The value to set on a `custom_field` dimension, shaped by its `fieldType`: an option value for `select`, a non-empty list of option values for `multiselect`, otherwise a boolean, string or number. Not accepted for other dimensions. oneOf: - type: string minLength: 1 maxLength: 255 - type: number - type: boolean - type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 255 applyToExistingEntries: type: boolean description: >- Also re-code existing entries whose transactions match the source, in the background. Only entries still `in_review` change; anything already synced or ready to sync is left alone. Has no effect on an `accounts_payable` mapping, which is read when a bill syncs. Defaults to `false`, which only affects entries created from now on. default: false required: - source - dimensionKey additionalProperties: false accounting-mapping: title: AccountingMapping description: >- A rule that codes one dimension automatically: whenever an entry's transaction involves the `source`, the entry gets the mapped value for `dimensionKey`. An `account` source codes the fixed, cash-side line of its transactions; every other source codes the editable lines, and `accounts_payable` sets the account bills are posted to when they sync. Sources are things you can already list through the API (accounts, cards, merchants, contacts, ...); the value is a dimension value id, or for custom-field dimensions the raw field value. One source maps each dimension at most once, so writing the same source and dimension again replaces the earlier mapping. type: object properties: id: type: string description: Mapping id with the `accounting_mapping_` prefix. example: accounting_mapping_2rj4l7hmrrrcv connectionId: type: string description: The connection the mapping belongs to. example: accounting_connection_2rj4l7hmrrrcv source: $ref: '#/components/schemas/accounting-mapping-source' dimensionKey: type: string description: >- The dimension this mapping codes, a `key` from `GET /v2/accounting/dimensions`. example: account valueId: type: string description: >- The dimension value applied, from `GET /v2/accounting/dimensions/{dimensionKey}/values`. Absent on custom-field mappings, which carry `customFieldValue` instead. example: accounting_account_2rj4l7hmrrrcv customFieldValue: description: >- The custom field value applied, present only when `dimensionKey` is a `custom_field` dimension. Its shape follows the field's `fieldType`: an option value for `select`, a list of option values for `multiselect`, otherwise a boolean, string or number. oneOf: - type: string - type: number - type: boolean - type: array items: type: string createdBy: type: string description: >- `user` for mappings written by people or the API, `ai` for mappings the accounting intelligence agent proposed and applied. enum: - user - ai createdAt: type: string format: date-time required: - id - connectionId - source - dimensionKey - createdAt additionalProperties: false accounting-mapping-source: title: AccountingMappingSource description: What a mapping keys on. type: object properties: type: type: string description: >- Which resource `id` names. `account` is an Account (`sa_group_`) and sets the cash-side account of its transactions; `virtual_account` (`subaccount_`), `card` (`c_`), `card_group` (`card_group_`), `merchant` (`merchant_v2_`, from a card transaction's `details.merchant.id`), `merchant_category` (`merchant_category_`, from a card transaction's `details.merchant.categoryId`) and `contact` (`le_c_`, the recipient of a transfer) code the expense side of matching transactions; `accounts_payable` takes no `id` and sets the accounts payable account bills are posted to. When several rules reach the same dimension of one transaction the more specific source wins, from weakest to strongest: `virtual_account`, `card_group`, `card`, `merchant_category`, `merchant`, `contact`. enum: - account - virtual_account - card - card_group - merchant - merchant_category - contact - accounts_payable id: type: string minLength: 1 maxLength: 255 description: >- The id of that resource. Required for every type except `accounts_payable`. example: c_2rj4l7hmrrrcv required: - type additionalProperties: false PublicApiV2ErrorConnectionIdRequired: title: PublicApiV2ErrorConnectionIdRequired description: >- The legal entity has several accounting connections, so the request must say which one with `connectionId`. List them with `GET /v2/accounting/connections`. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - connection_id_required details: type: object properties: field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. additionalProperties: false required: - code - details PublicApiV2ErrorCustomFieldValueInvalid: title: PublicApiV2ErrorCustomFieldValueInvalid description: >- The custom field does not exist in this scope, or the value does not match its type or options. `problem` says which. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - custom_field_value_invalid details: type: object properties: problem: type: string description: What is wrong with the value. example: Cost Center takes one option value. field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. required: - problem additionalProperties: false required: - code - details PublicApiV2ErrorDimensionDisabled: title: PublicApiV2ErrorDimensionDisabled description: >- The dimension is turned off for coding. Turn it on with `PATCH /v2/accounting/dimensions/{dimensionKey}`. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - dimension_disabled details: type: object properties: dimension: type: string description: The dimension’s name. example: Class field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. required: - dimension additionalProperties: false required: - code - details PublicApiV2ErrorDimensionNotMappable: title: PublicApiV2ErrorDimensionNotMappable description: >- The dimension only makes sense per entry, so mappings cannot set it. Its `mappable` is `false`. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - dimension_not_mappable details: type: object properties: dimension: type: string description: The dimension’s name. example: Purchase Order field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. required: - dimension additionalProperties: false required: - code - details PublicApiV2ErrorDimensionValueDisabled: title: PublicApiV2ErrorDimensionValueDisabled description: >- The value is turned off for coding. Turn it on with `PATCH /v2/accounting/dimensions/{dimensionKey}/values/{valueId}`. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - dimension_value_disabled details: type: object properties: dimension: type: string description: The dimension’s name. example: Account value: type: string description: The value’s name. example: 6100 Software Subscriptions field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. required: - dimension - value additionalProperties: false required: - code - details PublicApiV2ErrorMappingSourceNotAllowed: title: PublicApiV2ErrorMappingSourceNotAllowed description: >- This kind of source cannot set this dimension, for example an account on a class. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - mapping_source_not_allowed details: type: object properties: sourceType: type: string description: The `source.type` sent. example: account dimension: type: string description: The dimension’s name. example: Class field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. required: - sourceType - dimension additionalProperties: false required: - code - details PublicApiV2ErrorMappingValueMismatch: title: PublicApiV2ErrorMappingValueMismatch description: >- Custom field dimensions take `customFieldValue`; every other dimension takes `valueId`. `expected` names the one this dimension takes. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - mapping_value_mismatch details: type: object properties: dimension: type: string description: The dimension’s name. example: Cost Center expected: type: string description: '`valueId` or `customFieldValue`, whichever applies.' example: customFieldValue field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. required: - dimension - expected additionalProperties: false required: - code - details PublicApiV2ErrorInvalidRequestShape: title: PublicApiV2ErrorInvalidRequestShape description: >- The body, query, or headers failed validation, or a required header is missing. `details` has one entry per failing location, keyed by JSON pointer or header name. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - invalid_request details: type: object properties: {} additionalProperties: type: string required: - code - details PublicApiV2ErrorUnauthorized: title: PublicApiV2ErrorUnauthorized description: API key authentication is missing or invalid. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - unauthorized details: type: object properties: {} additionalProperties: false required: - code - details PublicApiV2ErrorForbidden: title: PublicApiV2ErrorForbidden description: >- The credential is not permitted to perform this action on the resource. When the resource is a field of the request, `details` names that `field` and the `id` it received. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - forbidden details: type: object properties: field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. additionalProperties: false required: - code - details PublicApiV2ErrorForbiddenLegalEntity: title: PublicApiV2ErrorForbiddenLegalEntity description: The credential is not permitted to act for the selected legal entity. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - forbidden details: type: object properties: {} additionalProperties: false required: - code - details PublicApiV2ErrorNotAvailable: title: PublicApiV2ErrorNotAvailable description: >- Public API v2 is not yet available. Use [Public API v1](https://docs.slash.com/introduction) in the meantime. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - not_available details: type: object properties: {} additionalProperties: false required: - code - details PublicApiV2ErrorUserApiKeyRequired: title: PublicApiV2ErrorUserApiKeyRequired description: >- The API key is scoped to a legal entity rather than a user. Every v2 request needs a user API key, created under Settings → API keys in the Slash dashboard, together with the `x-legal-entity` header. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - user_api_key_required details: type: object properties: {} additionalProperties: false required: - code - details PublicApiV2ErrorNotFound: title: PublicApiV2ErrorNotFound description: >- No resource matches the identifier. When the identifier is a field of the request, `details` names that `field` and the `id` it received. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - not_found details: type: object properties: field: type: string description: Dot path of the request field at fault. id: type: string description: The identifier that field carried, when it is one. additionalProperties: false required: - code - details PublicApiV2ErrorDefaultSubsidiaryRequired: title: PublicApiV2ErrorDefaultSubsidiaryRequired description: >- The platform keeps mappings per subsidiary, and the connection has no default subsidiary to read or write them for. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - default_subsidiary_required details: type: object properties: {} additionalProperties: false required: - code - details PublicApiV2ErrorInternal: title: PublicApiV2ErrorInternal description: >- Slash could not complete the request. Quote `referenceId` when contacting Slash support. allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - internal details: type: object properties: {} additionalProperties: false required: - code - details Error: type: object properties: code: type: string description: >- Machine-readable reason; branch on this, not on `message`. Every code an endpoint can return is listed on its reference page; the ones shared by all endpoints are explained in the Errors guide. example: invalid_request message: type: string description: >- Human-readable explanation, safe to show to an operator. Wording may change; use `code` and `details` programmatically. details: type: object description: >- The values behind `message`, keyed per `code`. For example `insufficient_funds` carries `available` and `requested`; `invalid_request` from contract validation carries one entry per failing field, keyed by JSON pointer. Empty when the code has no variable data. additionalProperties: type: string example: available: $120.00 requested: $500.00 referenceId: type: string description: Unique id of this failure. Quote it when contacting Slash support. example: 4001-2alj5if required: - code - message - details - referenceId additionalProperties: false title: Error responses: PublicApiV2Error400AccountingMappingsUpsert: description: >- - `connection_id_required` — The legal entity has several accounting connections, so the request must say which one with `connectionId`. List them with `GET /v2/accounting/connections`. - `custom_field_value_invalid` — The custom field does not exist in this scope, or the value does not match its type or options. `problem` says which. - `dimension_disabled` — The dimension is turned off for coding. Turn it on with `PATCH /v2/accounting/dimensions/{dimensionKey}`. - `dimension_not_mappable` — The dimension only makes sense per entry, so mappings cannot set it. Its `mappable` is `false`. - `dimension_value_disabled` — The value is turned off for coding. Turn it on with `PATCH /v2/accounting/dimensions/{dimensionKey}/values/{valueId}`. - `mapping_source_not_allowed` — This kind of source cannot set this dimension, for example an account on a class. - `mapping_value_mismatch` — Custom field dimensions take `customFieldValue`; every other dimension takes `valueId`. `expected` names the one this dimension takes. - `invalid_request (request shape)` — The body, query, or headers failed validation, or a required header is missing. `details` has one entry per failing location, keyed by JSON pointer or header name. content: application/json: schema: anyOf: - title: connection_id_required allOf: - $ref: '#/components/schemas/PublicApiV2ErrorConnectionIdRequired' - title: custom_field_value_invalid allOf: - $ref: >- #/components/schemas/PublicApiV2ErrorCustomFieldValueInvalid - title: dimension_disabled allOf: - $ref: '#/components/schemas/PublicApiV2ErrorDimensionDisabled' - title: dimension_not_mappable allOf: - $ref: '#/components/schemas/PublicApiV2ErrorDimensionNotMappable' - title: dimension_value_disabled allOf: - $ref: >- #/components/schemas/PublicApiV2ErrorDimensionValueDisabled - title: mapping_source_not_allowed allOf: - $ref: >- #/components/schemas/PublicApiV2ErrorMappingSourceNotAllowed - title: mapping_value_mismatch allOf: - $ref: '#/components/schemas/PublicApiV2ErrorMappingValueMismatch' - title: invalid_request (request shape) allOf: - $ref: '#/components/schemas/PublicApiV2ErrorInvalidRequestShape' examples: connection_id_required_connection_id: summary: connection_id_required (connectionId) value: code: connection_id_required message: >- connectionId is required because this legal entity has more than one accounting connection. details: field: connectionId id: accounting_connection_2rj4l7hmrrrcv referenceId: 4001-2alj5if custom_field_value_invalid_custom_field_value: summary: custom_field_value_invalid (customFieldValue) value: code: custom_field_value_invalid message: >- The custom field value is invalid: Cost Center takes one option value. details: problem: Cost Center takes one option value. field: customFieldValue referenceId: 4001-2alj5if dimension_disabled_dimension_key: summary: dimension_disabled (dimensionKey) value: code: dimension_disabled message: Class is disabled on this connection. details: dimension: Class field: dimensionKey referenceId: 4001-2alj5if dimension_not_mappable_dimension_key: summary: dimension_not_mappable (dimensionKey) value: code: dimension_not_mappable message: Purchase Order cannot be set by mappings on this connection. details: dimension: Purchase Order field: dimensionKey referenceId: 4001-2alj5if dimension_value_disabled_value_id: summary: dimension_value_disabled (valueId) value: code: dimension_value_disabled message: >- Account value "6100 Software Subscriptions" is disabled on this connection. details: dimension: Account value: 6100 Software Subscriptions field: valueId referenceId: 4001-2alj5if mapping_source_not_allowed_dimension_key: summary: mapping_source_not_allowed (dimensionKey) value: code: mapping_source_not_allowed message: A account mapping cannot set Class. details: sourceType: account dimension: Class field: dimensionKey referenceId: 4001-2alj5if mapping_value_mismatch_value_id: summary: mapping_value_mismatch (valueId) value: code: mapping_value_mismatch message: Cost Center is mapped with customFieldValue. details: dimension: Cost Center expected: customFieldValue field: valueId referenceId: 4001-2alj5if mapping_value_mismatch_custom_field_value: summary: mapping_value_mismatch (customFieldValue) value: code: mapping_value_mismatch message: Cost Center is mapped with customFieldValue. details: dimension: Cost Center expected: customFieldValue field: customFieldValue referenceId: 4001-2alj5if invalid_request_request_shape: summary: invalid_request (request shape) value: code: invalid_request message: >- Invalid `connectionId`: Expected a valid ID beginning with "accounting_connection_". details: /connectionId: Expected a valid ID beginning with "accounting_connection_". referenceId: 4001-2alj5if PublicApiV2Error401Unauthorized: description: '- `unauthorized` — API key authentication is missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/PublicApiV2ErrorUnauthorized' examples: unauthorized: summary: unauthorized value: code: unauthorized message: API key authentication is missing or invalid. details: {} referenceId: 4011-2alj5if PublicApiV2Error403ForbiddenForbiddenLegalEntityNotAvailableUserApiKeyRequired: description: >- - `forbidden` — The credential is not permitted to perform this action on the resource. When the resource is a field of the request, `details` names that `field` and the `id` it received. - `forbidden (legal entity)` — The credential is not permitted to act for the selected legal entity. - `not_available` — Public API v2 is not yet available. Use [Public API v1](https://docs.slash.com/introduction) in the meantime. - `user_api_key_required` — The API key is scoped to a legal entity rather than a user. Every v2 request needs a user API key, created under Settings → API keys in the Slash dashboard, together with the `x-legal-entity` header. content: application/json: schema: anyOf: - title: forbidden allOf: - $ref: '#/components/schemas/PublicApiV2ErrorForbidden' - title: forbidden (legal entity) allOf: - $ref: '#/components/schemas/PublicApiV2ErrorForbiddenLegalEntity' - title: not_available allOf: - $ref: '#/components/schemas/PublicApiV2ErrorNotAvailable' - title: user_api_key_required allOf: - $ref: '#/components/schemas/PublicApiV2ErrorUserApiKeyRequired' examples: forbidden: summary: forbidden value: code: forbidden message: This credential is not permitted to do that. details: {} referenceId: 4031-2alj5if forbidden_legal_entity: summary: forbidden (legal entity) value: code: forbidden message: This credential is not permitted to do that. details: {} referenceId: 4031-2alj5if not_available: summary: not_available value: code: not_available message: >- Public API v2 is not yet available. Use Public API v1 (https://docs.slash.com/introduction) in the meantime. details: {} referenceId: 4031-2alj5if user_api_key_required: summary: user_api_key_required value: code: user_api_key_required message: >- Public API v2 requires a user API key. Create one under Settings → API keys in the Slash dashboard. details: {} referenceId: 4031-2alj5if PublicApiV2Error404AccountingMappingsUpsert: description: >- - `not_found` — No resource matches the identifier. When the identifier is a field of the request, `details` names that `field` and the `id` it received. content: application/json: schema: $ref: '#/components/schemas/PublicApiV2ErrorNotFound' examples: not_found_connection_id: summary: not_found (connectionId) value: code: not_found message: >- `connectionId` accounting_connection_2rj4l7hmrrrcv was not found. details: field: connectionId id: accounting_connection_2rj4l7hmrrrcv referenceId: 4041-2alj5if not_found_source_id: summary: not_found (source.id) value: code: not_found message: '`source.id` was not found.' details: field: source.id referenceId: 4041-2alj5if not_found_dimension_key: summary: not_found (dimensionKey) value: code: not_found message: '`dimensionKey` was not found.' details: field: dimensionKey referenceId: 4041-2alj5if not_found_value_id: summary: not_found (valueId) value: code: not_found message: '`valueId` was not found.' details: field: valueId referenceId: 4041-2alj5if PublicApiV2Error409DefaultSubsidiaryRequired: description: >- - `default_subsidiary_required` — The platform keeps mappings per subsidiary, and the connection has no default subsidiary to read or write them for. content: application/json: schema: $ref: '#/components/schemas/PublicApiV2ErrorDefaultSubsidiaryRequired' examples: default_subsidiary_required: summary: default_subsidiary_required value: code: default_subsidiary_required message: >- This connection keeps mappings per subsidiary and has no default subsidiary yet. Pick one in the Slash dashboard first. details: {} referenceId: 4091-2alj5if PublicApiV2RateLimited: description: >- The request exceeded the applicable rate limit. The response body is plain text, not the error object; clients must not depend on its wording. content: text/plain: schema: type: string example: You are rate limited PublicApiV2Error500Internal: description: >- - `internal` — Slash could not complete the request. Quote `referenceId` when contacting Slash support. content: application/json: schema: $ref: '#/components/schemas/PublicApiV2ErrorInternal' examples: internal: summary: internal value: code: internal message: >- An unexpected error occurred. If this keeps happening, contact Slash support with the reference id below. details: {} referenceId: 5001-2alj5if securitySchemes: api_key: type: apiKey name: X-API-Key in: header description: >- User API key authentication. Create a key under Settings → API keys in the Slash dashboard (https://app.slash.com/global-settings/api-keys) and send the `x-legal-entity` header naming the legal entity to act on with every request. Keys scoped to a legal entity are rejected with `403 user_api_key_required`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.