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

# One mapping of a consumer: its rows, values and candidates

> The mapping's rows with their values, and one page of what a row may point at. Rows are what the source lists (or the fixed rows in use), then the keys an execution or a preview met without a value. Candidates are read from the consumer's connection: `refresh` reads them again, not from the connector's cache. The mapping's autofill rules run first, so a row they can fill has a value. Edit the values with `PATCH /consumers/{consumer_id}/syncs/{syncid}/mappings`.



## OpenAPI

````yaml get /consumers/{consumer_id}/syncs/{syncid}/mappings/{mapping_key}
openapi: 3.1.0
info:
  title: Chift API
  description: >-
    The Chift API is a universal API giving you access to financial data from
    the software of your clients. It helps software companies to offer native
    integrations to their clients without the effort needed to maintain those
    native integrations. By using the APIs (Accounting, POS, eCommerce) of
    Chift, you connect once and allow your clients to use their software
    packages.
  version: 1.0.0
servers:
  - url: https://api.chift.eu
    description: Chift
security:
  - bearerAuth: []
paths:
  /consumers/{consumer_id}/syncs/{syncid}/mappings/{mapping_key}:
    get:
      tags:
        - Syncs
      summary: 'One mapping of a consumer: its rows, values and candidates'
      description: >-
        The mapping's rows with their values, and one page of what a row may
        point at. Rows are what the source lists (or the fixed rows in use),
        then the keys an execution or a preview met without a value. Candidates
        are read from the consumer's connection: `refresh` reads them again, not
        from the connector's cache. The mapping's autofill rules run first, so a
        row they can fill has a value. Edit the values with `PATCH
        /consumers/{consumer_id}/syncs/{syncid}/mappings`.
      operationId: agentic_syncs_get_consumer_mapping
      parameters:
        - name: consumer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Consumer Id
        - name: syncid
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Syncid
        - name: mapping_key
          in: path
          required: true
          schema:
            type: string
            title: Mapping Key
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Keeps the candidates whose label or key contains it, ignoring
              case.
            title: Search
          description: Keeps the candidates whose label or key contains it, ignoring case.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page of candidates.
            default: 1
            title: Page
          description: Page of candidates.
        - name: size
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            description: Candidates per page.
            default: 100
            title: Size
          description: Candidates per page.
        - name: show_all
          in: query
          required: false
          schema:
            type: boolean
            description: Every item of the target, not only the suggested ones.
            default: false
            title: Show All
          description: Every item of the target, not only the suggested ones.
        - name: row
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              The row (its `source_key`) to suggest candidates for: a mapping
              can suggest per row.
            title: Row
          description: >-
            The row (its `source_key`) to suggest candidates for: a mapping can
            suggest per row.
        - name: refresh
          in: query
          required: false
          schema:
            type: boolean
            description: Read the rows and candidates from the connections again.
            default: false
            title: Refresh
          description: Read the rows and candidates from the connections again.
        - name: language
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              ISO 639-1 code of the language of the texts (en, fr, nl, de, es;
              any case), falling back to English. Without it, translation keys.
            title: Language
          description: >-
            ISO 639-1 code of the language of the texts (en, fr, nl, de, es; any
            case), falling back to English. Without it, translation keys.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingView'
        '400':
          content:
            application/json:
              examples:
                No connection:
                  value:
                    message: >-
                      The consumer has no connection to accounting chosen for
                      this sync
                    status: error
                Not supported:
                  value:
                    message: The resource GET - 'accounting/journals' is not supported
                    status: error
              schema:
                $ref: '#/components/schemas/ChiftError'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Sync not found:
                  value:
                    message: The sync does not exist
                    status: error
                Not configured:
                  value:
                    message: The consumer is not configured for this sync
                    status: error
                Mapping not needed:
                  value:
                    message: The consumer's sync does not need the mapping '{key}'
                    status: error
              schema:
                $ref: '#/components/schemas/ChiftError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MappingView:
      properties:
        key:
          type: string
          title: Key
          description: >-
            Stable key, e.g. 'spend_to_accounting.SupplierInvoices'. Send it
            back as is.
          examples:
            - spend_to_accounting.PurchaseVatCodes
        id:
          type: string
          format: uuid
          title: Id
          description: >-
            The stable uuid derived from the key, as the legacy sync routes
            identify the same item.
        title:
          type: string
          title: Title
          description: >-
            Name to show, in the requested language; its translation key without
            one.
        description:
          type: string
          title: Description
          description: >-
            What it does, the tooltip: in the requested language, its
            translation key without one.
        required:
          type: boolean
          title: Required
          description: >-
            A row without a value stops the objects that need it (an issue is
            raised).
        allow_delete:
          type: boolean
          title: Allow Delete
          description: The consumer may hide rows.
        target:
          anyOf:
            - type: string
              enum:
                - account
                - vat_code
                - journal
                - payment_account
                - analytic_plan
            - type: 'null'
          title: Target
          description: >-
            What the rows point at; null for a table of fixed options. A value
            missing from an 'account' table can be created with `POST
            …/mappings/{mapping_key}/accounts`.
        notice:
          anyOf:
            - type: string
            - type: 'null'
          title: Notice
          description: >-
            Why ai-fill left many rows to confirm, typically a source and a
            target that do not go together (country, chart of accounts, VAT
            regime). Null when nothing stands out.
        rows:
          items:
            $ref: '#/components/schemas/MappingRowView'
          type: array
          title: Rows
          description: >-
            The source's rows, then the keys met in the data, then any other row
            holding a value.
        candidates:
          $ref: '#/components/schemas/ChiftPage_MappingCandidate_'
          description: >-
            One page of what a row may point at, matching `search`: the
            suggested items sorted by label, then the mapping's fixed options.
            With `show_all`, every item of the target.
      type: object
      required:
        - key
        - id
        - title
        - description
        - required
        - allow_delete
        - target
        - notice
        - rows
        - candidates
      title: MappingView
      description: >-
        One mapping of a consumer: its rows with their values, and what they may
        point at.
    ChiftError:
      properties:
        message:
          type: string
          title: Message
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          default: error
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
          default: ''
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
      type: object
      required:
        - message
      title: ChiftError
    HTTPValidationError:
      title: Validation Error
      required:
        - message
      type: object
      properties:
        message:
          title: Message
          type: string
          default: Validation error
        status:
          title: Status
          type: string
          default: error
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    MappingRowView:
      properties:
        source_key:
          type: string
          title: Source Key
          description: The row's key, the value the sync looks up.
          examples:
            - '601000'
        label:
          type: string
          title: Label
          description: What to show for the row.
          examples:
            - 601000 Office supplies
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: The candidate key the row points at. Null when it has none.
        value_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Value Label
          description: The label of the value, when the target still lists it.
        origin:
          anyOf:
            - type: string
            - type: 'null'
          title: Origin
          description: >-
            Who wrote the value: 'human' (the consumer), 'sync_created' (the
            sync created what the consumer asked for), 'rule' (the sync's own
            autofill), 'ai' (ai-fill) or 'default'. A write never replaces a
            value of a higher rank: human = sync_created > rule > ai > default.
        hidden:
          type: boolean
          title: Hidden
          description: 'The consumer hid the row: it has no value, and no fill gives it one.'
        missing:
          type: boolean
          title: Missing
          description: >-
            An execution or the latest preview needed this row and it still has
            no value: it holds those objects up, and the mapping is incomplete
            until it is filled. The row may not be one the source lists.
        decision:
          anyOf:
            - type: string
              enum:
                - apply
                - confirm
                - ask
            - type: 'null'
          title: Decision
          description: >-
            What ai-fill decided for the row: 'apply' (it wrote the value),
            'confirm' (a likely value awaits the consumer's confirmation) or
            'ask' (the consumer must choose). Null when the row was not written
            by ai-fill.
        status:
          type: string
          enum:
            - open
            - to_confirm
            - settled
            - hidden
          title: Status
          description: >-
            'open' (no value yet), 'to_confirm' (ai-fill's value awaits the
            consumer), 'settled' (a value, or left empty by the consumer on a
            table that does without one) or 'hidden'.
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: Why ai-fill decided so, to show next to the row.
        question:
          anyOf:
            - type: string
            - type: 'null'
          title: Question
          description: What the consumer is asked when the decision is 'confirm' or 'ask'.
        purpose:
          anyOf:
            - type: string
            - type: 'null'
          title: Purpose
          description: >-
            For a fixed row, what its value is in accounting terms, as ai-fill
            is told it: a value that fits it follows the convention.
        suggestions:
          items:
            $ref: '#/components/schemas/MappingCandidate'
          type: array
          title: Suggestions
          description: The candidates ai-fill suggests for the row, the most likely first.
      type: object
      required:
        - source_key
        - label
        - value
        - value_label
        - origin
        - hidden
        - missing
        - decision
        - status
        - reason
        - question
        - suggestions
      title: MappingRowView
    ChiftPage_MappingCandidate_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/MappingCandidate'
          type: array
          title: Items
        total:
          type: integer
          minimum: 0
          title: Total
        page:
          type: integer
          minimum: 1
          title: Page
        size:
          type: integer
          minimum: 1
          title: Size
      type: object
      required:
        - items
        - total
        - page
        - size
      title: ChiftPage[MappingCandidate]
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    MappingCandidate:
      properties:
        key:
          type: string
          title: Key
          description: The value to store.
          examples:
            - '601000'
        label:
          type: string
          title: Label
          description: What to show.
          examples:
            - 601000 Office supplies
        fixed:
          type: boolean
          title: Fixed
          description: >-
            A fixed option of the mapping (e.g. 'to_be_created'), not an item of
            the target.
      type: object
      required:
        - key
        - label
        - fixed
      title: MappingCandidate
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        This access token needs to be included in each of your request to the
        Chift API.

````

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