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

# List contact imports

> Retrieve a paginated list of your contact imports — CSV uploads and connected-provider
syncs — most recently requested first. Each row mirrors the dashboard's import history:
type, processing status, contact counts, who requested it, when, and its review status.

`channel` selects which universe is listed: `email` (the default — contact imports and
provider syncs) or `sms` (SMS consent imports, a separate review pipeline). The two are
different record types with per-channel `status`/`review_status` vocabularies and count
keys; rows state their `channel`.

**Required scope:** `contacts_read`




## OpenAPI

````yaml openapi/privy-api.yaml GET /imports
openapi: 3.1.0
info:
  title: Privy API
  version: '1.0'
  description: >
    The Privy API lets you programmatically manage your contact list and read
    what you have set up in Privy.

    Create, update, unsubscribe, and remove contacts; report orders;

    and read your campaigns, flows, segments, orders, store products, coupon
    pools,

    performance reports, and account setup.
servers:
  - url: https://api.privy.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Retrieve information about the authenticated Privy account.
  - name: Contacts
    description: Manage your contact list.
  - name: Imports
    description: >-
      Read your contact import history — CSV uploads, connected-provider syncs,
      and SMS consent imports.
  - name: Campaigns
    description: >-
      Read your message campaigns — email and SMS newsletters, plus the messages
      your flows send.
  - name: Displays
    description: >-
      Read your on-site displays (popups, flyouts, banners, embedded forms,
      landing pages).
  - name: Coupons
    description: Read your coupon pools, their code inventory, and individual codes.
  - name: Reports
    description: >-
      Read performance reporting — signups, views, conversion rates, and
      attributed revenue — for your business, displays, and flows.
  - name: Flows
    description: Read your automation flows and their configuration.
  - name: Segments
    description: Read your customer segments and their membership.
  - name: Orders
    description: Report orders placed in your store and read your order history.
  - name: Products
    description: Read the product catalog and collections of your connected store.
  - name: Events
    description: Ingest custom events to trigger Flows and other automations.
paths:
  /imports:
    get:
      tags:
        - Imports
      summary: List contact imports
      description: >
        Retrieve a paginated list of your contact imports — CSV uploads and
        connected-provider

        syncs — most recently requested first. Each row mirrors the dashboard's
        import history:

        type, processing status, contact counts, who requested it, when, and its
        review status.


        `channel` selects which universe is listed: `email` (the default —
        contact imports and

        provider syncs) or `sms` (SMS consent imports, a separate review
        pipeline). The two are

        different record types with per-channel `status`/`review_status`
        vocabularies and count

        keys; rows state their `channel`.


        **Required scope:** `contacts_read`
      operationId: listImports
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: channel
          in: query
          description: Which import universe to list. Defaults to `email`.
          schema:
            type: string
            enum:
              - email
              - sms
        - name: status
          in: query
          description: >
            Filter by processing status. Email values: `pending`, `partial`,
            `successful`,

            `failed`. Not available on `channel=sms` for merchant tokens
            (`status` is

            omitted from their SMS rows) — the filter returns a `422` there.
          schema:
            type: string
        - name: review_status
          in: query
          description: >
            Filter by approval state. Email values: `NA`, `exempt`, `pending`,
            `approving`,

            `approved`, `auto_approved`, `partially_approved`, `rejected`. SMS
            values:

            `pending`, `approved`, `rejected`.
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of imports.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Import'
                  pagination:
                    $ref: '#/components/schemas/PaginationEnvelope'
              example:
                data:
                  - id: im_k2R5m8Q
                    channel: email
                    source: csv
                    status: partial
                    review_status: partially_approved
                    requested_by: Rita Requester
                    counts:
                      imported: 17506
                      new_contacts: 7615
                    created_at: '2026-08-08T17:52:00Z'
                pagination:
                  page: 1
                  per_page: 40
                  total_count: 3
                  total_pages: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
components:
  parameters:
    AccountIdParam:
      name: Privy-Account-Id
      in: header
      required: false
      description: >
        Target a subaccount instead of the main connected account.

        Pass a subaccount `id` from get_account's `subaccounts` list. Only
        direct subaccounts

        of the connected account are reachable — omit this for the main account
        itself.
      schema:
        type: string
      example: S1U2B3A4C5C6T7
    PageParam:
      name: page
      in: query
      description: Page number (starts at 1).
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 1
    PerPageParam:
      name: per_page
      in: query
      description: >-
        Number of results per page. Values outside 10–100 are clamped to the
        nearest bound.
      schema:
        type: integer
        default: 40
        minimum: 10
        maximum: 100
      example: 40
  schemas:
    Import:
      type: object
      description: >
        A contact import that created or updated contacts in bulk. Two channels
        share this

        shape: `email` (CSV uploads and connected-provider syncs) and `sms` (SMS
        consent

        imports, a separate review pipeline). Email imports create their
        contacts when the

        import is processed — shortly after `created_at`, before review — and
        approving the

        import then applies the pending consent (e.g. `never_subscribed` to
        `subscribed`).


        The base row is deliberately slim — the same facts the Privy dashboard's
        import

        history shows (`id`, `channel`, `source`, `status`, `review_status`,
        `requested_by`,

        `counts`, `created_at`).
      properties:
        id:
          type: string
          description: >
            Stable prefixed identifier (`im_…` email, `sim_…` sms). Use this
            value in

            `/v1/imports/{id}`; contacts reference email imports in
            `import_ids`.
          example: im_k2R5m8Q
        channel:
          type: string
          enum:
            - email
            - sms
          description: Which import pipeline the row belongs to.
          example: email
        source:
          type:
            - string
            - 'null'
          description: >
            The import mechanism, lowercased (`csv`, `shopify`, `mailchimp`, …).
            SMS consent

            imports are always `csv`.
          example: csv
        status:
          type:
            - string
            - 'null'
          description: >
            Processing outcome. Email values: `pending`, `partial`,
            `successful`, `failed`.

            Omitted on SMS rows for merchant tokens (the dashboard's SMS import
            history has

            no status column).
          example: partial
        review_status:
          type: string
          description: >
            Approval state. Email values: `NA` (review not required), `exempt`,
            `pending`,

            `approving`, `approved`, `auto_approved`, `partially_approved`,
            `rejected`.

            SMS values: `pending`, `approved`, `rejected`.
          example: approved
        requested_by:
          type:
            - string
            - 'null'
          description: >
            Display name of the merchant user who requested the import (for SMS
            consent

            imports, the TCPA compliance signer).
          example: Rita Requester
        counts:
          type:
            - object
            - 'null'
          description: >
            Outcome counts. Email keys: `imported`, `new_contacts`. SMS keys:
            `imported`,

            `rejected`, `ignored` (all audiences). Null on SMS rows until
            processing

            has produced real counts (pending/rejected imports) — never read
            null as zero.
          properties:
            imported:
              type: integer
              description: >-
                Contacts processed by the import, including ones that already
                existed.
            new_contacts:
              type: integer
              description: Contacts newly created by the import (email only).
            rejected:
              type: integer
            ignored:
              type: integer
        created_at:
          type: string
          format: date-time
    PaginationEnvelope:
      type: object
      properties:
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 25
        total_count:
          type: integer
          example: 142
        total_pages:
          type: integer
          example: 6
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - invalid_client
                - invalid_scope
                - unauthorized
                - insufficient_scope
                - paid_plan_required
                - api_access_required
                - not_found
                - no_connected_store
                - conflict
                - contacts_not_ready
                - validation_failed
                - rate_limited
                - store_unavailable
              example: validation_failed
            message:
              type: string
              example: One or more fields are invalid
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    example: email
                  message:
                    type: string
                    example: is required
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthorized
              message: Bearer token is missing or invalid
    InsufficientScope:
      description: Token lacks the required scope for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: insufficient_scope
              message: Token does not have the required scope
    ValidationFailed:
      description: One or more fields failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: validation_failed
              message: One or more fields are invalid
              details:
                - field: email
                  message: is required
    RateLimited:
      description: Rate limit exceeded. Retry after the specified time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 42
        X-RateLimit-Limit-Minute:
          description: Maximum requests allowed per minute.
          schema:
            type: integer
          example: 60
        X-RateLimit-Remaining-Minute:
          description: Requests remaining in the current minute window.
          schema:
            type: integer
          example: 0
        X-RateLimit-Reset-Minute:
          description: Unix timestamp when the minute window resets.
          schema:
            type: integer
          example: 1711929600
        X-RateLimit-Limit-Day:
          description: Maximum requests allowed per day.
          schema:
            type: integer
          example: 10000
        X-RateLimit-Remaining-Day:
          description: Requests remaining in the current day window.
          schema:
            type: integer
          example: 9500
        X-RateLimit-Reset-Day:
          description: Unix timestamp when the day window resets.
          schema:
            type: integer
          example: 1712016000
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token or OAuth access token
      description: >
        Send either an API token or an OAuth access token as

        `Authorization: Bearer <token>`. See the Authentication page for
        details.

````