---
title: "List mappers"
method: GET
path: "/v1/import/mappers"
tags: ["Import"]
---

# List mappers

`GET /v1/import/mappers`

## Request

- Base URL: `https://api.prod.keyban.io`
- URL: `https://api.prod.keyban.io/v1/import/mappers`
- Auth: API key in header `X-Api-Key`

Retrieve a paginated list of mappers for the authenticated organization. Supports filtering by application and name.

## Query parameters

- `filters` union[]
  - union
    - object
      - `operator` 'or' | 'and', required
      - `value` union[], required
        - union
          - object
            - `field` 'id', required
            - `operator` 'eq', required
            - `value` string, required
          - object
            - `field` 'createdAt', required
            - `operator` 'gt' | 'lt' | 'gte' | 'lte', required
            - `value` string, date-time, required
          - object
            - `field` 'updatedAt', required
            - `operator` 'gt' | 'lt' | 'gte' | 'lte', required
            - `value` string, date-time, required
          - object
            - `field` 'application.id', required
            - `operator` 'eq', required
            - `value` string, uuid, required
          - object
            - `field` 'name', required
            - `operator` 'eq' | 'contains', required
            - `value` string, required
          - object
            - `field` 'type', required
            - `operator` 'eq' | 'ne', required
            - `value` 'file' | 'url', required
    - object
      - `field` 'id', required
      - `operator` 'eq', required
      - `value` string, required
    - object
      - `field` 'createdAt', required
      - `operator` 'gt' | 'lt' | 'gte' | 'lte', required
      - `value` string, date-time, required
    - object
      - `field` 'updatedAt', required
      - `operator` 'gt' | 'lt' | 'gte' | 'lte', required
      - `value` string, date-time, required
    - object
      - `field` 'application.id', required
      - `operator` 'eq', required
      - `value` string, uuid, required
    - object
      - `field` 'name', required
      - `operator` 'eq' | 'contains', required
      - `value` string, required
    - object
      - `field` 'type', required
      - `operator` 'eq' | 'ne', required
      - `value` 'file' | 'url', required
- `sorters` object[]
  - `field` 'id' | 'createdAt' | 'updatedAt' | 'name' | 'createdAt' | 'updatedAt', required
  - `order` 'asc' | 'desc', required
- `currentPage` integer
- `pageSize` integer

## Response `200`

Mappers retrieved successfully

- PaginatedImportMapperDto
  - `data` object[], required: Array of items for the current page
    - `id` string, uuid, required: Entity UUID
    - `createdAt` string, date-time, required: Creation date (ISO 8601)
    - `updatedAt` string, date-time, required: Last update date (ISO 8601)
    - `application` string, uuid, required: UUID of the parent application owning the mapper.
    - `name` string, required: Human-readable mapper name. Must be unique within the parent application.
    - `type` 'file' | 'url', required: How the data is obtained: `file` (manual upload at import time) or `url` (file fetched on a recurring CRON schedule).
    - `url` string, uri, nullable, required: Absolute URL of the file fetched on each scheduled run. Null unless `type=url`.
    - `cronFrequency` string, nullable, required: CRON expression driving the scheduled fetch. Null unless `type=url`.
    - `csvHasHeader` boolean, nullable, required: Scheduled CSV sources only: whether the first fetched row is a header to skip (`true`) or already data (`false`). Null for `file` mappers and ignored when the fetched file is JSON.
    - `rows` object[], required: Ordered list of field mappings applied during import. Order is preserved and significant: later rows can overwrite earlier ones on the same `destination`.
      - `id` string, uuid, required: Entity UUID
      - `createdAt` string, date-time, required: Creation date (ISO 8601)
      - `updatedAt` string, date-time, required: Last update date (ISO 8601)
      - `type` 'const' | 'path' | 'column', required: How `source` is interpreted. `path` extracts a value from the imported JSON; `const` uses `source` as a literal value.
      - `source` string, required: Source value. JSONPath expression (RFC 9535) rooted at `$` when `type=path`, literal value when `type=const`.
      - `destination` string, required: Target field on the resulting model where the resolved value is written.
      - `position` integer, required: Zero-based position of the row within its mapper. Rows are applied in ascending position order during import.
    - `sourceStructure` union, required: Canonical structure of the sample file the mapper was built against, used to auto-detect the mapper matching an uploaded file. Null when the mapper predates the feature or was built without a usable header (never auto-detected until re-saved with a sample).
      - object
        - `format` 'csv', required: The sample was a CSV file with a header row.
        - `columns` string[], required: Normalized header names (lowercased, diacritics and non-alphanumerics stripped), in file order. Order is significant: CSV rows are mapped by column index.
      - object
        - `format` 'json', required: The sample was a JSON document (or array of documents).
        - `paths` string[], required: Sorted, deduplicated JSONPath expressions of the leaves of the first item.
  - `total` integer, required: Total count of items matching the query

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)