VitrinaAPI

Companies

The organisations contacts belong to. They group people; the legal identity lives on the contact that represents the company.

Beta
This may change at any time, with a changelog entry and a notice to recent callers — see versioning.

Download the full API pública projection: openapi.json.

Search, create and merge contacts explains this resource in prose, with runnable examples.

MethodPathWhat it does
GET/companiesList the workspace’s companies
POST/companiesCreate a company
DELETE/companies/{id}Delete a company
GET/companies/{id}Get a company
PUT/companies/{id}Update a company

GET /companies

List the workspace’s companies

Every company in alphabetical order, each with a contact_count — how many LIVE contacts name it (an archived or merged contact is not counted). q narrows the LIST by name; it does not narrow the counts, which describe the company rather than the search.

This list does not page and carries no meta: a workspace has companies, not hundreds of thousands of them. If that stops being true for a customer, it is a real change here rather than a limit they can guess at.

ParameterInTypeRequiredConstraints
qquerystringnomáx. 200
curl https://api.vitrinadev.com/api/v1/companies \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "15151515-0000-4000-8000-000000000001",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "name": "Constructora Andes SpA",
      "domain": "andes.cl",
      "industry": "Construcción",
      "size": "51-200",
      "website": "https://andes.cl",
      "phone": "+56223456789",
      "notes": "Cuenta corporativa — factura a fin de mes.",
      "metadata": {},
      "created_at": "2026-09-20T09:12:00.000Z",
      "updated_at": "2026-09-20T09:12:00.000Z",
      "contact_count": 7
    }
  ]
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /companies

Create a company

Only name is required. Nothing here is unique or validated against anything: two companies may share a domain, and creating the same name twice creates two rows — there is no dedup and no merge for companies, unlike contacts.

metadata is a free object an integration can use to keep its own ids and fields; it is stored verbatim and never interpreted.

Creating a company links nobody to it. Attach contacts afterwards with PATCH /contacts/\{id\} and company_id.

Body

FieldTypeRequiredConstraints
namestringyesmín. 1, máx. 300
domainstring | null—máx. 255
industrystring | null—máx. 200
sizestring | null—máx. 100
websitestring | null—máx. 500
phonestring | null—máx. 100
notesstring | null—máx. 5000
metadataobject—
curl -X POST https://api.vitrinadev.com/api/v1/companies \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Constructora Andes SpA",
    "domain": "andes.cl",
    "industry": "Construcción",
    "size": "51-200",
    "website": "https://andes.cl",
    "phone": "+56223456789"
  }'

Example response (201)

{
  "data": {
    "id": "15151515-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "Constructora Andes SpA",
    "domain": "andes.cl",
    "industry": "Construcción",
    "size": "51-200",
    "website": "https://andes.cl",
    "phone": "+56223456789",
    "notes": "Cuenta corporativa — factura a fin de mes.",
    "metadata": {},
    "created_at": "2026-09-20T09:12:00.000Z",
    "updated_at": "2026-09-20T09:12:00.000Z"
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /companies/{id}

Delete a company

⚠ Permanent — there is no archive for a company. The contacts survive: contact.company_id is set to null, so the people stay and only the grouping is gone. Nothing else references a company, so nothing else breaks.

Deleting a company from another workspace is a 404.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl -X DELETE https://api.vitrinadev.com/api/v1/companies/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /companies/{id}

Get a company

One company by uuid. A company from another workspace is a 404, never a 403 — the API does not confirm that an id it will not serve exists.

The single read does not carry contact_count; the list does. To get the people, ask GET /contacts/search?company_id=&lt;uuid&gt;.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/companies/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "id": "15151515-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "Constructora Andes SpA",
    "domain": "andes.cl",
    "industry": "Construcción",
    "size": "51-200",
    "website": "https://andes.cl",
    "phone": "+56223456789",
    "notes": "Cuenta corporativa — factura a fin de mes.",
    "metadata": {},
    "created_at": "2026-09-20T09:12:00.000Z",
    "updated_at": "2026-09-20T09:12:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /companies/{id}

Update a company

A PUT that behaves as a PATCH: send only the fields you are changing — at least one is required, and everything you leave out is kept. null clears a nullable field.

metadata is REPLACED as a whole when you send it, not merged key by key. Read it, change what you need, and write the complete object back.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
namestring—mín. 1, máx. 300
domainstring | null—máx. 255
industrystring | null—máx. 200
sizestring | null—máx. 100
websitestring | null—máx. 500
phonestring | null—máx. 100
notesstring | null—máx. 5000
metadataobject—
curl -X PUT https://api.vitrinadev.com/api/v1/companies/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Construcción e inmobiliaria",
    "size": "201-500"
  }'

Example response (200)

{
  "data": {
    "id": "15151515-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "Constructora Andes SpA",
    "domain": "andes.cl",
    "industry": "Construcción e inmobiliaria",
    "size": "201-500",
    "website": "https://andes.cl",
    "phone": "+56223456789",
    "notes": "Cuenta corporativa — factura a fin de mes.",
    "metadata": {},
    "created_at": "2026-09-20T09:12:00.000Z",
    "updated_at": "2026-09-22T11:30:18.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

Clinic bank feed

The clinic's bank movements, from e-mail, Fintoc or the bank's own API, normalized into one shape to reconcile the till.

Consignments

The contract under which a dealer sells someone else's car: create, edit, return and sell with its settlement.

On this page

GET /companiesPOST /companiesDELETE /companies/{id}GET /companies/{id}PUT /companies/{id}