---
updatedAt: 2026-05-26T04:18:35.000Z
agentTools:
  projectIndex: https://apidocs.apptoto.com/llms.txt
---

# /v1/import

Imports can be kicked off by uploading a CSV file to https://api.apptoto.com/v1/import

POST /v1/import kicks off an Import based on the data you pass in.  You can use GET /v1/import to fetch the Import information using the id provided to find out the result of the import.

Example Result:

```json
{
  "import": {
    "id": NUMERIC IDENTIFIER,
    "state": launching | running | invalid | finished | aborted
  }
}
```

### OAuth scope

Calls authenticated with an [OAuth 2.0](/reference/oauth-authentication) bearer token must include the `imports:write` scope. A token without it receives a `403` `insufficient_scope` response. HTTP Basic auth is not scope-gated.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "api-settings",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.apptoto.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      },
      "sec1": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://www.apptoto.com/oauth/authorize",
            "tokenUrl": "https://api.apptoto.com/oauth/token",
            "refreshUrl": "https://api.apptoto.com/oauth/token",
            "scopes": {
              "calendars:read": "View calendars",
              "address_books:read": "View address books",
              "contacts:read": "View contacts",
              "contacts:write": "Create, update, and delete contacts",
              "events:read": "View calendar events",
              "events:write": "Create, update, and delete events; mark event statuses",
              "bookings:read": "View booking page availability and existing bookings",
              "bookings:write": "Create bookings on booking pages",
              "imports:read": "Check the status of imports",
              "imports:write": "Upload imports (CSV / ICS / XML) that bulk-create data",
              "lists:read": "View opt-in and opt-out lists",
              "lists:write": "Modify opt-in and opt-out lists",
              "messaging:read": "View conversations and message history",
              "messaging:send": "Send SMS or email messages on the user's behalf",
              "webhooks:read": "View webhooks",
              "webhooks:write": "Create, update, and delete webhooks that send account activity to other services"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "sec0": []
    },
    {
      "sec1": []
    }
  ],
  "paths": {
    "/v1/import": {
      "post": {
        "summary": "/v1/import",
        "description": "Imports can be kicked off by uploading a CSV file to https://api.apptoto.com/v1/import",
        "operationId": "import-upload",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "data"
                ],
                "properties": {
                  "data": {
                    "type": "string",
                    "description": "The CSV or Tab-delimited file that Apptoto should import.  This parameter can either a string, or a file (using multipart/form-data)",
                    "format": "binary"
                  },
                  "based_on_import_id": {
                    "type": "integer",
                    "description": "Instead of providing a \"spec\" parameter, you can use Apptoto's Import UI to map columns to fields.  Once you've done that you can specify the import id of the existing import for the based_on_import_id parameter and Apptoto will use the settings from that previous import when running the new uploaded import.",
                    "format": "int32"
                  },
                  "spec": {
                    "type": "object",
                    "description": "The spec JSON tells Apptoto how to interpret the uploaded file.  If you specify a based_on_import_id value, then this field is not required as Apptoto will use the \"spec\" used in that import.",
                    "properties": {}
                  },
                  "target": {
                    "type": "string",
                    "description": "Can be either \"events\" or \"contacts\".  Defaults to \"events\".",
                    "default": "events"
                  },
                  "start_time": {
                    "type": "string",
                    "description": "Required when using the \"support_delete\" option.  This tells Apptoto the beginning of the time range of appointments that you are uploading.  Any appointments that are inside the time range but not included in the new upload will be removed if support_delete is turned on.",
                    "format": "date"
                  },
                  "end_time": {
                    "type": "string",
                    "description": "Required when using the \"support_delete\" option.  See start_time parameter above for more information.",
                    "format": "date"
                  },
                  "support_delete": {
                    "type": "boolean",
                    "description": "Supports removing any appointments on the server that are not listed in the upload between the start_time and end_time provided.  This is often set in the upload spec already, but you can override it here."
                  },
                  "support_update": {
                    "type": "boolean",
                    "description": "Supports updating any appointments on the server that are not listed in the upload between the start_time and end_time provided.  This is often set in the upload spec already, but you can override it here."
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": [
          {
            "sec0": []
          },
          {
            "sec1": [
              "imports:write"
            ]
          }
        ]
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```