> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Replace an operator fixed-width layout template > Fully replaces a stored per-tenant fixed-width layout template (records/fields/discriminator/recordWidths/requiredFields) by its id — a PUT full replace, not a sparse patch, since the byte-range invariants are whole-layout properties. The replacement is run through the SAME well-formedness gate the submission path enforces BEFORE storage: overrun, overlap, missing-required, zero-field, or a mis-marked money column (money MUST be kind=decimal) rejects with 422 and the stored template is left unchanged. Returns 404 when no active template matches, 409 when the new format key collides with another active template. Tenant from the JWT; never the body. ## OpenAPI ````yaml /pt/openapi/v3-current/matcher.yaml put /v1/imports/formats/templates/{templateId} openapi: 3.1.0 info: title: Matcher APIs description: >- Complete API reference for the Matcher reconciliation engine, providing automated transaction matching between Midaz Ledger and external systems. version: 6.1.0 license: name: Lerian Studio General License servers: - url: https://matcher.sandbox.lerian.net security: [] paths: /v1/imports/formats/templates/{templateId}: put: tags: - Ingestion summary: Replace an operator fixed-width layout template description: >- Fully replaces a stored per-tenant fixed-width layout template (records/fields/discriminator/recordWidths/requiredFields) by its id — a PUT full replace, not a sparse patch, since the byte-range invariants are whole-layout properties. The replacement is run through the SAME well-formedness gate the submission path enforces BEFORE storage: overrun, overlap, missing-required, zero-field, or a mis-marked money column (money MUST be kind=decimal) rejects with 422 and the stored template is left unchanged. Returns 404 when no active template matches, 409 when the new format key collides with another active template. Tenant from the JWT; never the body. operationId: updateLayoutTemplate parameters: - description: Layout template ID in: path name: templateId required: true schema: description: Layout template ID format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateLayoutTemplateRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/LayoutTemplateResponse' description: OK '400': description: The request contains invalid parameters or payload. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: 400-invalid-layout-template: $ref: >- #/components/examples/400-invalid-layout-template--put-v1-imports-formats-templates-templateid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: The requested resource was not found. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: mtch-0005-layout-template-not-found: $ref: >- #/components/examples/mtch-0005-layout-template-not-found--put-v1-imports-formats-templates-templateid '409': description: The request conflicts with the current state of the resource. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: mtch-0007-layout-template-already-exists-for-this-format: $ref: >- #/components/examples/mtch-0007-layout-template-already-exists-for-this-format--put-v1-imports-formats-templates-templateid '422': description: The request was well-formed but contains semantic errors. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: mtch-0006-layout-template-validation-catalog-field-overruns-record-wid: $ref: >- #/components/examples/mtch-0006-layout-template-validation-catalog-field-overruns-record-wid--put-v1-imports-formats-templates-templateid 422-validation-failed: $ref: '#/components/examples/422-validation-failed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: CreateLayoutTemplateRequest: additionalProperties: false properties: discriminatorLength: description: Discriminator width in bytes examples: - 1 format: int64 minimum: 1 type: integer discriminatorStart: description: Zero-based byte offset of the record-type discriminator examples: - 0 format: int64 minimum: 0 type: integer family: description: Format family the template namespaces under examples: - cnab400 minLength: 1 type: string records: description: Record types declared by the layout items: $ref: '#/components/schemas/LayoutTemplateRecordRequest' minItems: 1 type: - array - 'null' region: description: ISO alpha-2 region (uppercased) or XX examples: - BR minLength: 1 type: string requiredFields: description: Field names the variant must declare items: type: string type: - array - 'null' variant: description: Operator/brand variant axis examples: - acme-cobranca minLength: 1 type: string required: - region - family - variant - discriminatorStart - discriminatorLength - records type: object LayoutTemplateResponse: additionalProperties: false properties: createdAt: description: Creation timestamp (RFC 3339, UTC) examples: - '2025-01-15T10:30:00Z' format: date-time type: string discriminator: $ref: '#/components/schemas/LayoutTemplateDiscriminatorResponse' description: >- Record-type discriminator byte range the parser reads to select a record type formatKey: description: >- Canonical format descriptor key (region/family/variant) the template registers under examples: - br/cnab400/acme-cobranca type: string id: description: Template identifier examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string recordTypeCount: description: Number of record types the layout declares examples: - 1 format: int64 type: integer recordWidths: additionalProperties: format: int64 type: integer description: Per-record-type fixed width in bytes, keyed by record type type: object records: description: >- Record types the layout declares, each with its fixed width and ordered byte-range fields, sorted by record type items: $ref: '#/components/schemas/LayoutTemplateRecordResponse' type: - array - 'null' requiredFields: description: Field names the variant must declare across its record types items: type: string type: - array - 'null' variantKey: description: In-file variant key the layout is keyed by examples: - acme-cobranca type: string required: - id - formatKey - variantKey - recordTypeCount - discriminator - records - recordWidths - requiredFields - createdAt type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object LayoutTemplateRecordRequest: additionalProperties: false properties: fields: description: Ordered positional fields of this record type items: $ref: '#/components/schemas/LayoutTemplateFieldRequest' type: - array - 'null' recordType: description: Record-type value the discriminator byte slice must match (e.g. "1") examples: - '1' type: string width: description: Fixed width in bytes every record of this type must be examples: - 33 format: int64 type: integer required: - recordType - width - fields type: object LayoutTemplateDiscriminatorResponse: additionalProperties: false properties: length: description: Discriminator width in bytes examples: - 1 format: int64 type: integer startByte: description: Zero-based byte offset of the record-type discriminator examples: - 0 format: int64 type: integer required: - startByte - length type: object LayoutTemplateRecordResponse: additionalProperties: false properties: fields: description: Ordered positional fields of this record type items: $ref: '#/components/schemas/LayoutTemplateFieldResponse' type: - array - 'null' recordType: description: Record-type value the discriminator byte slice matches (e.g. "1") examples: - '1' type: string width: description: Fixed width in bytes every record of this type must be examples: - 33 format: int64 type: integer required: - recordType - width - fields type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object RateLimitErrorResponse: description: >- Flat body that the rate limiter returns. `code` is the HTTP status as a number. type: object required: - code - title - message properties: code: type: integer description: HTTP status code. example: 429 title: type: string description: Error type. example: rate_limit_exceeded message: type: string description: Human-readable error message. example: rate limit exceeded LayoutTemplateFieldRequest: additionalProperties: false properties: kind: description: >- Value type: string (raw text), decimal (money/numeric verbatim token, parsed downstream), or date. A money column MUST be decimal — declaring it string or date is refused by the server-side submission gate, which the schema enum does not replace enum: - string - decimal - date examples: - decimal type: string length: description: Field width in bytes (must be greater than 0) examples: - 12 format: int64 type: integer name: description: >- Canonical field name this byte slice feeds (e.g. external_id, amount, currency, date) examples: - amount type: string startByte: description: Zero-based byte offset where the field begins examples: - 11 format: int64 type: integer required: - name - startByte - length - kind type: object LayoutTemplateFieldResponse: additionalProperties: false properties: kind: description: >- Value type: string (raw text), decimal (money/numeric verbatim token, parsed downstream), or date enum: - string - decimal - date examples: - decimal type: string length: description: Field width in bytes examples: - 12 format: int64 type: integer name: description: >- Canonical field name this byte slice feeds (e.g. external_id, amount, currency, date) examples: - amount type: string startByte: description: Zero-based byte offset where the field begins examples: - 11 format: int64 type: integer required: - name - startByte - length - kind type: object examples: 400-invalid-layout-template--put-v1-imports-formats-templates-templateid: summary: Invalid layout template value: title: Bad Request status: 400 detail: >- The layout template definition is invalid (a malformed descriptor, record, or field); the stored template was not changed. Correct the layout and try again. mtch-0005-layout-template-not-found--put-v1-imports-formats-templates-templateid: summary: Layout template not found value: type: https://errors.lerian.studio/v1/MTCH-0005 title: Not Found status: 404 detail: >- No active layout template matches this id; the update was not applied. Check the layout template id and try again. code: MTCH-0005 mtch-0007-layout-template-already-exists-for-this-format--put-v1-imports-formats-templates-templateid: summary: Layout template already exists for this format value: type: https://errors.lerian.studio/v1/MTCH-0007 title: Conflict status: 409 detail: >- Another layout template already uses this format key; the update was not applied. Choose a different format key and try again. code: MTCH-0007 mtch-0006-layout-template-validation-catalog-field-overruns-record-wid--put-v1-imports-formats-templates-templateid: summary: >- Layout template validation: catalog field overruns record width: variant... value: type: https://errors.lerian.studio/v1/MTCH-0006 title: Unprocessable Entity status: 422 detail: >- The replacement layout did not pass validation: its fields overlap, run past the record width, leave a required field unmapped, or define a record with no fields. The stored template was not changed. Correct the layout and try again. code: MTCH-0006 422-validation-failed: summary: Validation failed value: title: Unprocessable Entity status: 422 detail: validation failed responses: Unauthorized: description: The request lacks valid authentication credentials. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: MissingToken: summary: Missing token value: type: https://errors.lerian.studio/v1/AUT-0006 title: Token Missing status: 401 detail: >- A valid token must be provided in the request header. Please include a token and try again. code: AUT-0006 InvalidToken: summary: Invalid token value: type: https://errors.lerian.studio/v1/AUT-0007 title: Invalid Token status: 401 detail: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. code: AUT-0007 Forbidden: description: You do not have permission to access this resource. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: TenantClaimRequired: summary: Tenant claim missing value: type: https://errors.lerian.studio/v1/MTCH-0004 title: Forbidden status: 403 detail: tenant claim required code: MTCH-0004 PermissionDenied: summary: Permission denied value: type: https://errors.lerian.studio/v1/AUT-1020 title: Permission Denied status: 403 detail: >- the credential is not allowed to perform contexts:read on this request code: AUT-1020 TooManyRequests: description: >- The request exceeded the rate limit. Wait the number of seconds in `Retry-After`, then retry. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' example: code: 429 title: rate_limit_exceeded message: rate limit exceeded InternalServerError: description: An unexpected error occurred on the server. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' example: type: https://errors.lerian.studio/v1/MTCH-0002 title: Internal Server Error status: 500 detail: internal error code: MTCH-0002 text/plain: schema: type: string example: Internal Server Error headers: RetryAfter: description: Seconds to wait before you retry. schema: type: integer example: 30 XRateLimitLimit: description: Requests allowed in the current window. schema: type: integer example: 100 XRateLimitRemaining: description: Requests left in the current window. Always `0` on a `429`. schema: type: integer example: 0 XRateLimitReset: description: Unix time, in seconds, when the current window resets. schema: type: integer example: 1767225600 securitySchemes: BearerAuth: bearerFormat: JWT description: 'Bearer token authentication (format: "Bearer {token}")' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.