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

# Create Import

> Create a new import

The `payload` is an array of objects, where each object will be imported. For all three types, we expect the same payload you would also send to their respective `/x_details` endpoint.

To simplify integrations, deals and appointments both accept an additional `contact_external_id` that can be set instead of the `contact_id`.

For cross-contact updates by external ID, set `allow_deal_reassignment` for deals or `allow_appointment_reassignment` for appointments.

### Parsing Phone Numbers

For `contact_details` imports, we also accept a list of phone numbers for both `whatsapp` and `sms`:

```json theme={null}
{
  "whatsapp": ["+493813901", "+18494383"],
  "sms": ["+493813901", "+18494383"]
}
```

We will parse each option and use the first valid phone number out of the list as the input. To improve accuracy, you can pass a `country_codes` array along:

```json theme={null}
{
  "whatsapp": ["+493813901", "+18494383"],
  "sms": ["+493813901", "+18494383"],
  "country_codes": ["DE", "AT"]
}
```

This means you do not have to call the `/format` endpoint separately. It will be handled within the import.


## OpenAPI

````yaml post /import
openapi: 3.1.0
info:
  title: Mateo API
  description: The official API for Mateo
  version: 1.0.0
servers:
  - url: https://integration.getmateo.com/api/v1
security:
  - bearerAuth: []
externalDocs:
  description: Documentation for Mateo API
  url: https://docs.getmateo.com
paths:
  /import:
    post:
      tags:
        - Import
      summary: Create Import
      description: Create a new import
      parameters:
        - name: select
          in: query
          description: Filtering Columns
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Type of import
                  format: public.import_type
                  enum:
                    - contact_details
                    - deal_details
                    - appointment_details
                payload:
                  type: object
                  description: Payload of import for small imports
                  format: jsonb
                  nullable: true
                contact_list_id:
                  type: string
                  description: >-
                    ID of the contact list that the contacts should be assigned
                    to
                  format: uuid
                  nullable: true
                contact_list_external_id:
                  type: string
                  description: >-
                    External ID of the contact list that the contacts should be
                    assigned to
                  format: text
                  nullable: true
                allow_deal_reassignment:
                  type: boolean
                  description: >-
                    If true, a deal currently assigned to another contact will
                    be re-assigned
                  format: boolean
                  nullable: true
                allow_appointment_reassignment:
                  type: boolean
                  description: >-
                    If true, an appointment currently assigned to another
                    contact will be re-assigned
                  format: boolean
                  nullable: true
        description: import
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/import'
          description: The updated Import object
        '201':
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/import'
                    title: Import
                  - title: Empty
                    type: object
                    properties: {}
          description: The Import was created
        '204':
          content: {}
          description: No Content
components:
  schemas:
    import:
      type: object
      properties:
        id:
          type: string
          description: Import ID
          format: uuid
          default: random uuid
        created_at:
          type: string
          description: Import creation date
          format: timestamp with time zone
          default: now()
        updated_at:
          type: string
          description: Latest update
          format: timestamp with time zone
          default: now()
        organisation_id:
          type: string
          description: Organisation ID
          format: uuid
        type:
          type: string
          description: Type of import
          format: public.import_type
          enum:
            - contact_details
            - deal_details
            - appointment_details
        payload:
          type: object
          description: Payload of import for small imports
          format: jsonb
          nullable: true
        contact_list_id:
          type: string
          description: ID of the contact list that the contacts should be assigned to
          format: uuid
          nullable: true
        contact_list_external_id:
          type: string
          description: >-
            External ID of the contact list that the contacts should be assigned
            to
          format: text
          nullable: true
        failed_url:
          type: string
          description: URL to download the failed contacts
          format: text
          nullable: true
        payload_url:
          type: string
          description: URL to download the payload for large imports
          format: text
          nullable: true
        total_count:
          type: integer
          description: Total number of contacts in the import
          format: integer
          nullable: true
        success_count:
          type: integer
          description: Number of contacts successfully imported
          format: integer
          nullable: true
        failed_count:
          type: integer
          description: Number of contacts that failed to import
          format: integer
          nullable: true
        reference_id:
          type: string
          description: An optional reference ID provided during the import
          format: text
          nullable: true
        hints:
          type: object
          description: >-
            Optional hints for the import, e.g. to indicate if a field was
            stolen from another contact. We only store the first 20 hints.
          format: jsonb
          nullable: true
        allow_deal_reassignment:
          type: boolean
          description: >-
            If true, a deal currently assigned to another contact will be
            re-assigned
          format: boolean
          nullable: true
        allow_appointment_reassignment:
          type: boolean
          description: >-
            If true, an appointment currently assigned to another contact will
            be re-assigned
          format: boolean
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````