Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vern.so/llms.txt

Use this file to discover all available pages before exploring further.

POST https://app.vern.so/api/v1/companies
Creates a company with an associated workbook (one sheet per selected template) and a magic link the customer can use to share data.

​
Authentication

Requires an x-api-key header. See Authentication.

​
Request body

​
name
string
required
Display name for the company. Typically your customer’s organization name.
​
source
string (uuid)
required
The UUID of the integration the customer will authenticate against. Find this in Settings → Sources.
​
email
string
required
Email of an existing teammate in your Vern account. Used as the created_by for the new workbook.
​
external_id
string
Your own identifier for this customer (e.g. their ID in your database). Returned on every webhook for the resulting workbook, so you can match it back. Max 255 characters; alphanumeric, hyphens, and underscores only. Must be unique within your account.
​
template_ids
string[] (uuids)
Which templates to create sheets from. If omitted, every template in your account is used.

​
Response

201 Created 
{
  "company": {
    "id": "uuid",
    "name": "Acme Corp",
    "external_id": "customer_42",
    "created_at": "2026-05-12T15:32:11.000Z"
  },
  "workbook_id": "uuid",
  "sheets": [
    { "id": "uuid", "name": "Employees", "template_id": "uuid" },
    { "id": "uuid", "name": "Projects", "template_id": "uuid" }
  ],
  "magic_link_url": "https://app.vern.so/link/abc123"
}
The magic link expires after 7 days. Refresh it from the company’s page in the dashboard.

​
Errors

StatusMeaning
400name, source, or email missing; external_id malformed; template_ids invalid.
401API key missing or invalid.
404The source UUID isn’t an integration in your account, or the email isn’t a teammate.
409external_id already used by another company in your account.
429Rate limit hit — back off and retry.
500Server error.

​
Example

curl -X POST https://app.vern.so/api/v1/companies \
  -H "x-api-key: $VERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "source": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "ops@yourco.com",
    "external_id": "customer_42"
  }'

​
Next

  • Webhooks — receive cleaned data for the new company once its workbook is exported.