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

# Import Contacts

> Import contacts from CSV (base64) or direct array.



## OpenAPI

````yaml /api-reference/openapi.json post /contacts/import
openapi: 3.1.0
info:
  title: Truedy API
  description: >-
    Truedy Public API. Authenticate with **Authorization: Bearer
    <your-api-key>** only. Get your API key from the [Truedy
    Dashboard](https://app.truedy.ai). Base URL:
    https://api.truedy.ai/api/public/v1
  version: 1.0.0
servers:
  - url: https://api.truedy.ai/api/public/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create, configure, test, retrieve, and delete voice agents.
  - name: Calls
    description: >-
      Create and manage outbound calls, recordings, transcripts, and call
      metadata.
  - name: Tools
    description: Create and manage agent tools.
  - name: Knowledge Bases
    description: Legacy Ultravox-backed knowledge bases and sources.
  - name: Knowledge Spaces
    description: >-
      Truedy-native RAG knowledge spaces, sources, ingestion jobs, and
      retrieval.
  - name: Voices
    description: Browse, import, clone, synchronize, preview, and delete voices.
  - name: Telephony
    description: Search, purchase, import, assign, unassign, and release phone numbers.
  - name: Batch Calls
    description: Create and manage outbound batch calling campaigns and their contacts.
  - name: Contacts
    description: Manage contact folders, contacts, imports, and exports.
  - name: Calls
    description: Start browser-based Web Calls with an active agent.
  - name: Widgets
    description: Manage New Frontend widget configurations and embed sessions.
  - name: Agent Templates
    description: Read active agent templates available to the organization.
  - name: Call Explainability
    description: Retrieve redacted structured evidence for a call.
  - name: Webhooks
    description: Manage organization webhook endpoints and delivery history.
  - name: Analytics
    description: Read organization dashboard and conversation intelligence analytics.
  - name: Exports
    description: Export organization calls and campaigns as CSV.
  - name: Workspaces
    description: Create and manage workspaces with an account-scoped master API key.
paths:
  /contacts/import:
    post:
      tags:
        - Contacts
      summary: Import Contacts
      description: Import contacts from CSV (base64) or direct array.
      operationId: import_contacts_api_public_v1_contacts_import_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactImportRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicContactImportResponse'
        '401':
          $ref: '#/components/responses/PublicUnauthorized'
        '403':
          $ref: '#/components/responses/PublicForbidden'
        '422':
          $ref: '#/components/responses/PublicValidationError'
        '429':
          $ref: '#/components/responses/PublicRateLimitExceeded'
        '500':
          $ref: '#/components/responses/PublicInternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    ContactImportRequest:
      properties:
        folder_id:
          type: string
          title: Folder Id
          description: Folder ID to import contacts into
        file_key:
          anyOf:
            - type: string
            - type: 'null'
          title: File Key
          description: Storage key for uploaded CSV file (legacy)
        contacts:
          anyOf:
            - items:
                $ref: '#/components/schemas/ContactCreate'
              type: array
            - type: 'null'
          title: Contacts
          description: Direct contact data array (legacy)
        csv_base64:
          anyOf:
            - type: string
            - type: 'null'
          title: Csv Base64
          description: Base64 encoded CSV file content
        base64_file:
          anyOf:
            - type: string
            - type: 'null'
          title: Base64 File
          description: Base64 encoded CSV file content (legacy alias for csv_base64)
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: Original filename of the CSV
        mapping_config:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Mapping Config
          description: >-
            Mapping from CSV headers to standard fields. Format: {'csv_header':
            'standard_field'}. Unmapped fields go to metadata.
      type: object
      required:
        - folder_id
      title: ContactImportRequest
    PublicContactImportResponse:
      properties:
        data:
          $ref: '#/components/schemas/ContactImportResponse'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      type: object
      required:
        - data
        - meta
      title: PublicContactImportResponse
    ContactCreate:
      properties:
        folder_id:
          type: string
          title: Folder Id
          description: Folder ID to add contact to
        first_name:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: First Name
          description: First name
        last_name:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Last Name
          description: Last name
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Email address
        phone_number:
          type: string
          title: Phone Number
          description: Phone number in E.164 format
        company_name:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Company Name
          description: Company name
        industry:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Industry
          description: Industry
        location:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Location
          description: Location
        pin_code:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Pin Code
          description: Pin code
        keywords:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Keywords
          description: Keywords (array)
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Additional metadata
      type: object
      required:
        - folder_id
        - phone_number
      title: ContactCreate
    ContactImportResponse:
      properties:
        successful:
          type: integer
          title: Successful
          description: Number of successfully imported contacts
        failed:
          type: integer
          title: Failed
          description: Number of failed imports
        errors:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Errors
          description: List of errors with row numbers
      type: object
      required:
        - successful
        - failed
      title: ContactImportResponse
    ResponseMeta:
      properties:
        request_id:
          type: string
          title: Request Id
          description: Unique request identifier for support and debugging
        ts:
          type: string
          format: date-time
          title: Ts
          description: Server timestamp when the response was generated
      type: object
      required:
        - request_id
        - ts
      title: ResponseMeta
      description: Metadata included in every API response.
    PublicApiErrorResponse:
      type: object
      required:
        - error
        - meta
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
            details:
              description: >-
                Structured, endpoint-specific details. Never rely on
                undocumented provider fields.
              type:
                - object
                - array
                - 'null'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          description: Request correlation metadata.
      example:
        error:
          code: validation_error
          message: 'Missing required field: name'
          details:
            errors: []
        meta:
          request_id: req_01JEXAMPLE
          ts: '2026-08-21T00:00:00Z'
  responses:
    PublicUnauthorized:
      description: Missing, malformed, expired, inactive, or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicForbidden:
      description: >-
        The API key is valid but the request is not permitted by its
        organization, IP allowlist, or scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicValidationError:
      description: The request is syntactically valid but fails endpoint validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicRateLimitExceeded:
      description: >-
        The API key or organization exceeded a configured request limit. Retry
        after the response headers/window indicate.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
          description: Seconds until retry is permitted, when available.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Configured request limit.
        X-RateLimit-Remaining:
          schema:
            type: integer
            minimum: 0
          description: Remaining requests in the current window.
        X-RateLimit-Reset:
          schema:
            type: string
            format: date-time
          description: UTC time at which the current window resets.
    PublicInternalError:
      description: Unexpected server failure. Use meta.request_id when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Your API key. Send in the Authorization header as: Bearer <your-api-key>'

````