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

# Upload a CSV of contacts with a consent attestation



## OpenAPI

````yaml /api-reference/openapi.json post /v1/contacts/imports
openapi: 3.1.0
info:
  description: >-
    Larynth control-plane API v1. Errors are RFC 9457 problem+json with a stable
    type URI per code (x-larynth-error-codes). Operations carry
    x-larynth-min-role, x-larynth-auth, x-larynth-scope, x-larynth-idempotency
    and x-larynth-sdk.
  title: Larynth API
  version: 1.0.0
servers:
  - url: https://api-us.larynth.com
    description: US region
security: []
tags:
  - description: Dashboard login and session. Excluded from SDKs.
    name: auth
    x-larynth-sdk: false
  - description: Tenant settings and members. Dashboard session only.
    name: tenants
    x-larynth-sdk: true
  - description: API keys. Dashboard session only.
    name: api-keys
    x-larynth-sdk: true
  - description: Activity log and its exports. Dashboard session only.
    name: audit
    x-larynth-sdk: true
  - description: >-
      Notification preferences, Slack and Telegram channels, browser push.
      Dashboard session only.
    name: notifications
    x-larynth-sdk: true
  - description: >-
      Export and deletion requests for a workspace or account. Dashboard session
      only.
    name: data-rights
    x-larynth-sdk: true
  - description: Models and voices available to assistants.
    name: catalog
    x-larynth-sdk: true
  - description: Assistants and their immutable published versions.
    name: assistants
    x-larynth-sdk: true
  - description: >-
      Phone numbers, routing hours, area codes, branded calling and
      bring-your-own SIP trunks.
    name: numbers
    x-larynth-sdk: true
  - description: Contacts and CSV imports.
    name: contacts
    x-larynth-sdk: true
  - description: >-
      Consent, revocations, do-not-call, pre-dial decisions, outbound readiness
      and calling rules.
    name: compliance
    x-larynth-sdk: true
  - description: >-
      Business and identity verification that unlocks outbound calling.
      Dashboard session only.
    name: verification
    x-larynth-sdk: true
  - description: Outbound campaigns.
    name: campaigns
    x-larynth-sdk: true
  - description: Calls, turns and events.
    name: calls
    x-larynth-sdk: true
  - description: Encrypted call recordings.
    name: recordings
    x-larynth-sdk: true
  - description: Prepaid balance, ledger, top-ups and rates (micro-USD).
    name: billing
    x-larynth-sdk: true
  - description: Webhook endpoints and deliveries (Standard Webhooks signatures).
    name: webhooks
    x-larynth-sdk: true
  - description: >-
      Knowledge bases built from files and websites, attached to assistant
      versions.
    name: knowledge
    x-larynth-sdk: true
  - description: Live updates over WebSocket. Dashboard session only.
    name: realtime
    x-larynth-sdk: true
  - description: Platform operator endpoints. Excluded from SDKs.
    name: admin
    x-larynth-sdk: false
  - description: Workspaces of the signed-in user. Dashboard session only.
    name: workspaces
    x-larynth-sdk: true
  - description: >-
      Spending requests from Members to Owners and Admins. Dashboard session
      only.
    name: spending
    x-larynth-sdk: true
  - description: Home brief and setup checklist. Dashboard session only.
    name: home
    x-larynth-sdk: true
  - description: Shared action inbox of a workspace. Dashboard session only.
    name: inbox
    x-larynth-sdk: true
paths:
  /v1/contacts/imports:
    post:
      tags:
        - contacts
      summary: Upload a CSV of contacts with a consent attestation
      operationId: createContactImport
      parameters:
        - description: >-
            Replays within 24 h return the stored response; the same key with a
            different body returns 409
          in: header
          name: Idempotency-Key
          required: true
          schema:
            description: >-
              Replays within 24 h return the stored response; the same key with
              a different body returns 409
            maxLength: 255
            minLength: 8
            type: string
      requestBody:
        content:
          multipart/form-data:
            encoding:
              attestation_text:
                contentType: text/plain
              campaign_id:
                contentType: text/plain
              consent_kind:
                contentType: text/plain
              consent_source:
                contentType: text/plain
              covers_marketing:
                contentType: text/plain
              evidence_text:
                contentType: text/plain
              file:
                contentType: text/csv,application/vnd.ms-excel,text/plain
              mapping:
                contentType: text/plain
              mode:
                contentType: text/plain
              tag:
                contentType: text/plain
              validated_import_id:
                contentType: text/plain
            schema:
              properties:
                attestation_text:
                  description: Attestation of how consent was obtained
                  maxLength: 4000
                  minLength: 20
                  type: string
                campaign_id:
                  description: Also enrol every imported contact in this campaign
                  format: uuid
                  type: string
                consent_kind:
                  enum:
                    - express
                    - express_written
                  type: string
                consent_source:
                  enum:
                    - import
                    - web_form
                    - paper_form
                    - verbal_recorded
                    - customer_agreement
                    - other
                  type: string
                covers_marketing:
                  description: express_written only
                  enum:
                    - 'true'
                    - 'false'
                  type: string
                evidence_text:
                  description: Consent wording or evidence shown to the contacts
                  maxLength: 2000
                  minLength: 10
                  type: string
                file:
                  contentEncoding: binary
                  contentMediaType: application/octet-stream
                  description: >-
                    CSV of at most 10,000 rows and 10 MB; required unless
                    validated_import_id is given
                  format: binary
                  type: string
                mapping:
                  description: >-
                    JSON array of ImportColumnMapping; without it the fixed
                    header names apply
                  maxLength: 8000
                  type: string
                mode:
                  description: >-
                    validate returns the review counts without importing;
                    default commit
                  enum:
                    - validate
                    - commit
                  type: string
                tag:
                  description: Added to every imported contact
                  pattern: ^[a-z0-9][a-z0-9 _-]{0,23}$
                  type: string
                validated_import_id:
                  description: >-
                    Commit a validated import without sending the file again (24
                    h)
                  format: uuid
                  type: string
              required:
                - attestation_text
              type: object
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactImport'
          description: Accepted
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '409':
          $ref: '#/components/responses/Problem409'
        '410':
          $ref: '#/components/responses/Problem410'
        '413':
          $ref: '#/components/responses/Problem413'
        '422':
          $ref: '#/components/responses/Problem422'
        '429':
          $ref: '#/components/responses/Problem429'
        '500':
          $ref: '#/components/responses/Problem500'
      security:
        - session: []
        - apiKey:
            - contacts:write
components:
  schemas:
    ContactImport:
      additionalProperties: false
      properties:
        attested_at:
          format: date-time
          type: string
        attested_by:
          format: uuid
          type: string
        campaign_id:
          format: uuid
          type: string
        consent_kind:
          enum:
            - express
            - express_written
          type: string
        consent_source:
          enum:
            - import
            - web_form
            - paper_form
            - verbal_recorded
            - customer_agreement
            - other
          type: string
        covers_marketing:
          type: boolean
        created_at:
          format: date-time
          type: string
        error:
          type: string
        evidence_text:
          type: string
        expires_at:
          description: A validated import can be committed until then
          format: date-time
          type: string
        finished_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        mapping:
          items:
            $ref: '#/components/schemas/ImportColumnMapping'
          type: array
        mode:
          enum:
            - validate
            - commit
          type: string
        phase:
          enum:
            - validating
            - validated
            - importing
            - done
            - failed
          type: string
        preview:
          $ref: '#/components/schemas/ImportPreview'
        progress:
          format: double
          maximum: 1
          minimum: 0
          type: number
        rejects_ready:
          type: boolean
        rows_ok:
          format: int64
          type: integer
        rows_rejected:
          format: int64
          type: integer
        rows_total:
          format: int64
          type: integer
        status:
          enum:
            - uploaded
            - processing
            - done
            - failed
          type: string
        tag:
          type: string
      required:
        - id
        - status
        - rows_total
        - rows_ok
        - rows_rejected
        - attested_by
        - attested_at
        - created_at
        - progress
        - covers_marketing
        - rejects_ready
      type: object
    ImportColumnMapping:
      additionalProperties: false
      properties:
        column:
          maxLength: 100
          minLength: 1
          type: string
        key:
          description: Variable name for attr
          pattern: ^[a-z][a-z0-9_]{0,39}$
          type: string
        target:
          enum:
            - phone
            - first_name
            - last_name
            - timezone
            - tag
            - attr
            - consent_evidence
            - relationship
            - skip
          type: string
      required:
        - column
        - target
      type: object
    ImportPreview:
      additionalProperties: false
      properties:
        dnc:
          description: Saved but not called
          format: int64
          type: integer
        duplicate_in_file:
          format: int64
          type: integer
        existing_updated:
          description: >-
            Existing contacts keep their details and gain this import's consent
            record
          format: int64
          type: integer
        invalid:
          format: int64
          type: integer
        non_us:
          format: int64
          type: integer
        problems:
          items:
            $ref: '#/components/schemas/ImportProblem'
          maxItems: 200
          type: array
        ready:
          format: int64
          type: integer
        rows_total:
          format: int64
          type: integer
      required:
        - rows_total
        - ready
        - invalid
        - non_us
        - dnc
        - duplicate_in_file
        - existing_updated
        - problems
      type: object
    Problem:
      additionalProperties: true
      properties:
        api_base:
          description: API base URL of the workspace's home region (workspace.other_region)
          type: string
        attempts_left:
          description: Code attempts left in this sign-in step
          format: int64
          type: integer
        campaign_ids:
          description: Campaigns that use the number (numbers.in_use)
          items:
            type: string
          type: array
        checks:
          description: Failed launch checks (campaign.preflight_failed)
          items:
            $ref: '#/components/schemas/PreflightCheck'
          type: array
        code:
          description: >-
            Stable machine-readable error code; compliance denials carry the
            dial.* rule id
          type: string
        contact_id:
          description: Existing contact (contacts.exists)
          type: string
        detail:
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        instance:
          type: string
        optout_line:
          description: The number is the opt-out line (numbers.in_use)
          type: boolean
        reauth_methods:
          description: Ways to re-authenticate, in preference order (auth.reauth_required)
          items:
            type: string
          type: array
        request_kind:
          description: Spending request kind to file instead (spending.approval_required)
          enum:
            - number_purchase
            - campaign_launch
          type: string
        retry_at:
          description: Next moment the request may succeed (calling windows)
          format: date-time
          type: string
        revision:
          description: >-
            Current revision (numbers.routing_conflict,
            campaign.revision_conflict)
          format: int64
          type: integer
        status:
          format: int64
          type: integer
        title:
          type: string
        type:
          description: Stable URI identifying the error code
          type: string
        updated_by_name:
          type: string
      required:
        - type
        - title
        - status
        - code
      type: object
    ImportProblem:
      additionalProperties: false
      properties:
        kind:
          enum:
            - invalid
            - non_us
            - dnc
            - duplicate
            - existing
          type: string
        reason_code:
          type: string
        row:
          format: int64
          type: integer
        value_masked:
          type: string
      required:
        - row
        - value_masked
        - kind
        - reason_code
      type: object
    PreflightCheck:
      additionalProperties: false
      properties:
        code:
          enum:
            - platform_outbound_open
            - verification
            - telemarketing_approved
            - paid_top_up
            - outbound_terms
            - script_check
            - agent_published
            - caller_id
            - audience
            - consent_coverage
            - dnc_internal
            - dnc_national
            - calling_hours
            - frequency_cap
            - holidays_sundays
            - ca_preamble
            - state_registrations
            - voicemail_optout_line
            - balance
            - daily_spend_cap
            - recheck_due
          type: string
        fix:
          $ref: '#/components/schemas/CheckFix'
        params:
          additionalProperties: {}
          type: object
        state:
          enum:
            - ok
            - warn
            - stop
            - info
          type: string
      required:
        - code
        - state
      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
    CheckFix:
      additionalProperties: false
      properties:
        kind:
          enum:
            - link
            - step
          type: string
        target:
          description: Dashboard route or wizard step
          type: string
      required:
        - kind
        - target
      type: object
  responses:
    Problem400:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Bad Request
    Problem401:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Unauthorized
    Problem403:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Forbidden
    Problem409:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Conflict
    Problem410:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Gone
    Problem413:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Request Entity Too Large
    Problem422:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Unprocessable Entity
    Problem429:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Too Many Requests
    Problem500:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Internal Server Error
  securitySchemes:
    session:
      description: Dashboard session cookie
      in: cookie
      name: __Host-lx_session
      type: apiKey
    apiKey:
      bearerFormat: lx_<key_id>_<secret>
      description: API key; the listed scope is required
      scheme: bearer
      type: http

````

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