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

# Upload a contact CSV

> Verifies the CSV, then creates the valid rows that are not already on the account. Invalid and duplicate rows are reported and not saved. The same file field and column overrides as verification are accepted.



## OpenAPI

````yaml /openapi.json post /public/v1/contacts/csv
openapi: 3.0.3
info:
  title: Callin Public API
  version: 1.0.0
  description: >-
    The Callin public API lets you programmatically build and manage AI voice
    agents, control their knowledge bases, and retrieve call logs and
    transcripts. All endpoints are versioned under /public/v1.
servers:
  - url: https://api.callin.io/api
    description: API Endpoint
security: []
tags:
  - name: Health
    description: Service availability check. No authentication required.
  - name: Identity
    description: Verify which account is associated with the current API key.
  - name: Agents
    description: Create, retrieve, and update AI voice agents.
  - name: Conversations
    description: List and inspect call logs, transcripts, and conversation details.
  - name: Knowledge Base
    description: Manage documents and groups that agents use during calls.
  - name: Campaigns
    description: ...
  - name: Contacts
    description: ...
paths:
  /public/v1/contacts/csv:
    post:
      tags:
        - Contacts
      summary: Upload a contact CSV
      description: >-
        Verifies the CSV, then creates the valid rows that are not already on
        the account. Invalid and duplicate rows are reported and not saved. The
        same file field and column overrides as verification are accepted.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ContactCsvUpload'
      responses:
        '200':
          description: Verification plus the contacts that were created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessContactCsvImportResponse'
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
        - ApiKeyQuery: []
components:
  schemas:
    ContactCsvUpload:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: UTF-8 .csv file, up to 10MB and 2000 data rows.
        phoneColumn:
          type: string
          description: >-
            Header to use as the phone number when it is not named phone or
            phoneNumber.
        nameColumn:
          type: string
        emailColumn:
          type: string
    SuccessContactCsvImportResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessContactCsvVerifyResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                created:
                  type: array
                  items:
                    $ref: '#/components/schemas/Contact'
                skipped:
                  type: array
                  items:
                    type: object
                createdCount:
                  type: integer
                skippedCount:
                  type: integer
    SuccessContactCsvVerifyResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            fileName:
              type: string
            delimiter:
              type: string
              enum:
                - comma
                - semicolon
                - tab
            headers:
              type: array
              items:
                type: string
            mapping:
              type: object
              properties:
                phoneNumber:
                  type: string
                name:
                  type: string
                  nullable: true
                email:
                  type: string
                  nullable: true
            summary:
              type: object
              properties:
                rowCount:
                  type: integer
                validCount:
                  type: integer
                invalidCount:
                  type: integer
                duplicateCount:
                  type: integer
                existingCount:
                  type: integer
            rows:
              type: array
              items:
                $ref: '#/components/schemas/ContactCsvRow'
        requestId:
          type: string
          nullable: true
    Contact:
      type: object
      properties:
        contactId:
          type: string
        phoneNumber:
          type: string
        name:
          type: string
        email:
          type: string
        metadata:
          type: object
          properties:
            createdAt:
              type: string
              nullable: true
      additionalProperties: true
    ContactCsvRow:
      type: object
      properties:
        row:
          type: integer
          description: Spreadsheet row number. The header is row 1.
        status:
          type: string
          enum:
            - valid
            - invalid
            - duplicate
            - existing
        contact:
          $ref: '#/components/schemas/ContactWrite'
        reasons:
          type: array
          items:
            type: string
    ContactWrite:
      type: object
      properties:
        phoneNumber:
          type: string
        name:
          type: string
        email:
          type: string
      additionalProperties: true
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Send your Callin API key in the `x-api-key` header.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Same API key as a Bearer token: `Authorization: Bearer <your-api-key>`.'

````

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