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

# Create Contact List

> Creates a contact list from rows of contact data, the same way a CSV upload does in the web app. Send the CSV's header row as `columns` and the remaining rows as `rows`, and use `field_mappings` to choose which columns to import.

The import runs in the background and returns `202` straight away with the list in `uploading` status. Poll `Retrieve Contact List` until its status is `active` (or `verifying` while emails are being verified) before using it in a campaign.



## OpenAPI

````yaml /openapi-v1.yml post /api/v1/contact-list/
openapi: 3.1.1
info:
  title: DeliverymanAI API V1
  version: 1.0.0
  description: >-
    API documentation for version 1 of the DeliverymanAI API. These endpoints
    drive campaigns, contact lists, leads and email sequences from your own
    code.


    V1 and V2 share the same API keys, sent in the `X-Api-Key` header.
servers:
  - url: https://api.deliveryman.ai
    description: Deliveryman API Server
security: []
paths:
  /api/v1/contact-list/:
    post:
      tags:
        - Contact List
      summary: Create Contact List
      description: >-
        Creates a contact list from rows of contact data, the same way a CSV
        upload does in the web app. Send the CSV's header row as `columns` and
        the remaining rows as `rows`, and use `field_mappings` to choose which
        columns to import.


        The import runs in the background and returns `202` straight away with
        the list in `uploading` status. Poll `Retrieve Contact List` until its
        status is `active` (or `verifying` while emails are being verified)
        before using it in a campaign.
      operationId: contact_list_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactListRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetContactListAPI'
          description: Import Started
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleMessageResponse'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleMessageResponse'
          description: Workspace Not Found
        '500':
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleMessageResponse'
          description: Not Available Yet
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: bash
          label: curl
          source: |-
            curl -X POST "https://api.deliveryman.ai/api/v1/contact-list/" \
              -H "X-Api-Key: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "workspace_id": 12,
                "name": "Q1 outreach",
                "columns": [],
                "rows": [],
                "field_mappings": [],
                "unsubscribe_column": "string",
                "verify_emails": true
              }'
components:
  schemas:
    CreateContactListRequest:
      properties:
        workspace_id:
          description: ID of the workspace to create the contact list in.
          title: Workspace Id
          type: integer
        name:
          description: Name of the contact list. Max 300 characters.
          maxLength: 300
          minLength: 1
          title: Name
          type: string
        columns:
          description: >-
            Column names, in the same order as the values in each row. Column
            names must be unique.
          examples:
            - - Email
              - First Name
              - Company
          items:
            minLength: 1
            type: string
          minItems: 1
          title: Columns
          type: array
        rows:
          description: >-
            Contact rows, excluding the header row. Each row lists values in
            `columns` order. Missing trailing values are treated as empty and
            extra values are ignored. Rows with a duplicate email address are
            skipped. At most 100000 rows.
          examples:
            - - - jane@example.com
                - Jane
                - Acme
          items:
            items:
              type: string
            type: array
          maxItems: 100000
          minItems: 1
          title: Rows
          type: array
        field_mappings:
          description: >-
            Which columns to import and the contact field each one is stored as.
            Exactly one column must be mapped to `Email Address`. Columns that
            aren't mapped are not imported.
          items:
            $ref: '#/components/schemas/ContactListFieldMapping'
          minItems: 1
          title: Field Mappings
          type: array
        unsubscribe_column:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Column that marks contacts as unsubscribed. Contacts whose value in
            this column is `yes`, `true` or `1` (case-insensitive) are imported
            as unsubscribed and never emailed.
          title: Unsubscribe Column
        verify_emails:
          default: true
          description: >-
            Whether to verify the contacts' email addresses after the import.
            Verification may be unavailable for some accounts, in which case it
            is skipped.
          title: Verify Emails
          type: boolean
      required:
        - workspace_id
        - name
        - columns
        - rows
        - field_mappings
      title: CreateContactListRequest
      type: object
    GetContactListAPI:
      type: object
      properties:
        uid:
          type: string
          description: UID of this contact list.
          maxLength: 255
        workspace_id:
          type: integer
          readOnly: true
          description: ID of workspace this contact list belongs to.
        name:
          type: string
          description: Name of the contact list.
          maxLength: 300
        created_on:
          type: string
          format: date-time
          readOnly: true
          description: >-
            Timestamp of when the contact list was created. ISO format date
            string in UTC timezone.
        status:
          type: string
          description: >-
            Current status of the contact list: `uploading` while contacts are
            being imported, `verifying` while email addresses are being
            verified, `active` when it's ready to use, or `failed` if the import
            failed.
          maxLength: 100
        source:
          type: string
          description: Source of the contact list.
          maxLength: 300
        available_columns:
          description: List of columns available in the contact list.
        has_unsubscribe_column:
          type: boolean
          description: Indicates if the contact list contains an unsubscribe column.
        unsubscribe_column_name:
          type:
            - string
            - 'null'
          description: Name of the unsubscribe column, if present.
          maxLength: 300
        contacts_count:
          type: integer
          maximum: 2147483647
          minimum: 0
          description: Number of contacts in the contact list.
        email_verification_status:
          allOf:
            - $ref: '#/components/schemas/EmailVerificationStatusEnum'
          description: |-
            Status of email address verification for this list.

            * `processing` - Processing
            * `completed` - Completed
            * `skipping` - Skipping
            * `skipped` - Skipped
            * `failed` - Failed
            * `N/A` - Not Applicable
        field_mappings:
          type: array
          items:
            $ref: '#/components/schemas/ContactListFieldMappingResponse'
          readOnly: true
          description: How the list's columns map to contact fields.
        is_deletable:
          type: boolean
          description: >-
            False while the list is used by a campaign that is created,
            scheduled, running or paused.
          readOnly: true
      required:
        - created_on
        - field_mappings
        - is_deletable
        - name
        - uid
        - workspace_id
    SimpleMessageResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the result or error.
      required:
        - message
    ContactListFieldMapping:
      properties:
        column:
          description: Column name from `columns`.
          title: Column
          type: string
        mapped_field:
          allOf:
            - $ref: '#/components/schemas/MappedFieldEnum'
          description: >-
            Contact field this column is stored as. Use `Custom Field` to store
            the column under your own name given in `custom_field_name`. Mapped
            fields can be used as variables in email sequences.
          title: Mapped Field
        custom_field_name:
          anyOf:
            - maxLength: 100
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Name of the custom field. Required when `mapped_field` is `Custom
            Field`, and must be omitted otherwise.
          title: Custom Field Name
      required:
        - column
        - mapped_field
      title: ContactListFieldMapping
      type: object
    EmailVerificationStatusEnum:
      enum:
        - processing
        - completed
        - skipping
        - skipped
        - failed
        - N/A
      type: string
      description: |-
        * `processing` - Processing
        * `completed` - Completed
        * `skipping` - Skipping
        * `skipped` - Skipped
        * `failed` - Failed
        * `N/A` - Not Applicable
    ContactListFieldMappingResponse:
      type: object
      properties:
        column:
          type: string
          description: Column name the field was imported from.
        mapped_field:
          type: string
          description: Contact field the column is stored as.
        custom_field_name:
          type:
            - string
            - 'null'
          description: Name of the custom field, if `mapped_field` is `Custom Field`.
      required:
        - column
        - mapped_field
    MappedFieldEnum:
      enum:
        - Email Address
        - First Name
        - Last Name
        - Company Name
        - Website
        - Phone Number
        - LinkedIn Profile
        - Custom Field
      type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Your API key, sent as the value of the `X-Api-Key` header. In the
        dashboard, go to Integrations and open Deliveryman API Keys to create
        one.

````

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