Create a migration

POST https://app.vern.so/api/v1/migrations

Creates a migration for one of your customers — a workbook with one sheet per template. You can name the system you’re migrating from in the source field, but no import logic is bound to the migration: the managed agent decides what to run. Later calls reference only the migration ID. A new migration starts in awaiting_files — your next step is to give it data, either by uploading files or by connecting a live source.

Authentication

Requires an x-api-key header — this endpoint requires API-key auth specifically (a session token is rejected). The key is scoped to your account and can address every migration in it. See Authentication.

Request body

name

string

required

Display name for the migration. Typically your customer’s organization name.

source

string

The name of the source this migration comes from — the system its data is coming out of. List your sources to find it. Optional: omit it (or pass null/empty) for a sourceless migration, where the agent works purely from the uploaded files.

external_id

string

Your own identifier for this customer (e.g. their ID in your database). Echoed back so you can match the migration to your records. Max 255 characters; alphanumeric, hyphens, and underscores only. Makes creation idempotent — re-sending the same external_id (with the same source) returns the existing migration with a 200. See Errors & limits.

templates

string[]

The slugs of the templates to create sheets from — the objects this customer will import. List your templates to choose. If omitted, every active template in your account is used.

Response

201 Created (or 200 OK when an existing migration is returned via external_id idempotency).

{
  "migration": {
    "id": "c0a8012e-4f1b-4d3a-9b2c-7e6f5a4b3c2d",
    "name": "Acme Corp",
    "source": "Salesforce",
    "status": "awaiting_files",
    "templates": [
      { "slug": "contacts", "name": "Contacts" }
    ]
  }
}

migration.id

string (uuid)

The migration ID — pass it to every run and export call.

migration.name

string

The display name you provided.

migration.source

string | null

The source name, or null for a sourceless migration.

migration.status

string

The migration’s overall state. awaiting_files for a fresh migration; for one returned via idempotency it reflects progress so far (awaiting_files, ready, awaiting_approval, or completed). See Core concepts → Migration.

migration.templates

object[]

The templates that became sheets, each { slug, name }.

Errors

Status	Meaning
`400`	`name` missing; `source` not a string; `external_id` malformed; `templates` not an array of slugs; one or more template slugs not found (`Unknown template slug(s): …`).
`401`	API key missing or invalid, or the request used a session token instead of an API key.
`404`	The named `source` isn’t a source in your account.
`409`	`external_id` already used by another migration, the source name is ambiguous (two sources share it), or your account’s region isn’t live yet.
`429`	Rate limit hit — back off and retry.
`500`	Server error.

See Errors & limits for the shared error model.

Example

curl -X POST https://app.vern.so/api/v1/migrations \
  -H "x-api-key: $VERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "source": "Salesforce",
    "external_id": "acme-001",
    "templates": ["contacts"]
  }'

Upload files — push the customer’s data into the migration.
Connect a live source — extract from an API instead of files.
Start a run — generate a preview once data is in place.

Overview

Get started

API reference

Reference

Authentication

Request body

Response

Errors

Example

Next

​Authentication

​Request body

​Response

​Errors

​Example

​Next

Authentication

Request body

Response

Errors

Example

Next