companies

14 endpoints at a glance

Method	Path	Summary
GET	/companies	List Companies
POST	/companies	Create Company
DELETE	/companies/{company_id}	Delete Company
GET	/companies/{company_id}	Get Company
PATCH	/companies/{company_id}	Update Company
POST	/companies/{company_id}/enrich	Enrich Company
GET	/companies/{company_id}/members	List Members
POST	/companies/{company_id}/members	Add Member
DELETE	/companies/{company_id}/members/{member_username}	Remove Member
PATCH	/companies/{company_id}/members/{member_username}	Change Member Role
POST	/companies/{company_id}/validate-vat	Validate Company Vat
POST	/companies/discover-from-contacts	Discover From Contacts
GET	/companies/kvk/{kvk_number}	Kvk Profile
GET	/companies/kvk/search	Kvk Search

companies

---

Kvk Search

GET

/companies/kvk/search

Search the KVK register by company name or KVK number.

Parameters

Header Parameters

authorization

Query Parameters

q*

Type

string

Required

page

Type

integer

Default

1

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/companies/kvk/search

Playground

Headers

authorization

Variables

Key

Value

q*

page

Samples

---

Kvk Profile

GET

/companies/kvk/{kvk_number}

Fetch one company's KVK basisprofiel (structured address) for auto-fill.

Parameters

Header Parameters

authorization

Path Parameters

kvk_number*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/companies/kvk/{kvk_number}

Playground

Headers

authorization

Variables

Key

Value

kvk_number*

Samples

---

List Companies

GET

/companies

Parameters

Header Parameters

authorization

Query Parameters

q

page

Type

integer

Default

1

limit

Type

integer

Default

50

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/companies

Playground

Headers

authorization

Variables

Key

Value

q

page

limit

Samples

---

Create Company

POST

/companies

Parameters

Header Parameters

authorization

Request Body

application/json

{

  

"name": "string",

  

"website": "string",

  

"industry": "string",

  

"size": "string",

  

"description": "string",

  

"address": "string",

  

"email": "string",

  

"vat_number": "string",

  

"kvk_number": "string",

  

"iban": "string",

  

"billing_address": {

  

  

"street": "string",

  

  

"postal_code": "string",

  

  

"city": "string",

  

  

"country": "string"

  

},

  

"notes_md": "string",

  

"tag_ids": [

  

  

"string"

  

]

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/companies

Playground

Headers

authorization

Body

Samples

---

Get Company

GET

/companies/{company_id}

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/companies/{company_id}

Playground

Headers

authorization

Variables

Key

Value

company_id*

Samples

---

Delete Company

DELETE

/companies/{company_id}

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/companies/{company_id}

Playground

Headers

authorization

Variables

Key

Value

company_id*

Samples

---

Update Company

PATCH

/companies/{company_id}

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

Request Body

application/json

{

  

"name": "string",

  

"website": "string",

  

"industry": "string",

  

"size": "string",

  

"description": "string",

  

"address": "string",

  

"email": "string",

  

"vat_number": "string",

  

"kvk_number": "string",

  

"iban": "string",

  

"billing_address": {

  

  

"street": "string",

  

  

"postal_code": "string",

  

  

"city": "string",

  

  

"country": "string"

  

},

  

"notes_md": "string",

  

"tag_ids": [

  

  

"string"

  

],

  

"custom_fields": {

  

  

"additionalProperties": "string"

  

}

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PATCH

/companies/{company_id}

Playground

Headers

authorization

Variables

Key

Value

company_id*

Body

Samples

---

Enrich Company

POST

/companies/{company_id}/enrich

Ask DeepSeek to describe this company. Writes nothing.

Returns the proposal alongside the current values so the SPA can show them
side by side; the user applies what they want via the normal PATCH. Scope
is descriptive only (industry / size / description) — legal and billing
identifiers come from KVK and VIES, never from a language model, because
they are snapshotted onto invoices.

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/companies/{company_id}/enrich

Playground

Headers

authorization

Variables

Key

Value

company_id*

Samples

---

Validate Company Vat

POST

/companies/{company_id}/validate-vat

Validate the company's VAT number against VIES and cache the result.

A definitive valid/invalid answer is stored as such. If VIES (or the
member state's system) is unreachable, we store an error status and
still return 200 — the UI shows a "couldn't verify, try again" state
rather than treating it as an invalid number.

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/companies/{company_id}/validate-vat

Playground

Headers

authorization

Variables

Key

Value

company_id*

Samples

---

Discover From Contacts

POST

/companies/discover-from-contacts

Scan every contact's parsed.organization and bootstrap.

For each non-empty org string:

• get-or-create a Company by that name
• get-or-create a works_at edge from the contact to the company

Returns counts so the SPA can show a summary. Safe to re-run; both
sides dedupe.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/companies/discover-from-contacts

Playground

Headers

authorization

Samples

---

List Members

GET

/companies/{company_id}/members

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/companies/{company_id}/members

Playground

Headers

authorization

Variables

Key

Value

company_id*

Samples

---

Add Member

POST

/companies/{company_id}/members

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

Request Body

application/json

{

  

"username": "string",

  

"role": "editor"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/companies/{company_id}/members

Playground

Headers

authorization

Variables

Key

Value

company_id*

Body

Samples

---

Remove Member

DELETE

/companies/{company_id}/members/{member_username}

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

member_username*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/companies/{company_id}/members/{member_username}

Playground

Headers

authorization

Variables

Key

Value

company_id*

member_username*

Samples

---

Change Member Role

PATCH

/companies/{company_id}/members/{member_username}

Parameters

Header Parameters

authorization

Path Parameters

company_id*

Type

string

Required

member_username*

Type

string

Required

Request Body

application/json

{

  

"role": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PATCH

/companies/{company_id}/members/{member_username}

Playground

Headers

authorization

Variables

Key

Value

company_id*

member_username*

Body

Samples

---