Companies

Companies represent the legal entities that send invoices through Mandato. Each company has a VAT number, a country, and can have one or more connections to government e-invoicing systems.

You must create at least one company before submitting invoices.

Company object

{
  "id": "comp_a1b2c3d4e5f6",
  "name": "TechVision SRL",
  "vatNumber": "RO12345678",
  "country": "RO",
  "currency": "RON",
  "isActive": true,
  "createdAt": "2025-01-10T09:00:00.000Z"
}

Fields

Field	Type	Description
`id`	`string`	Unique company identifier
`name`	`string`	Legal company name
`vatNumber`	`string`	VAT identification number (with country prefix)
`country`	`string`	ISO 3166-1 alpha-2 country code
`currency`	`string`	Default currency (ISO 4217)
`isActive`	`boolean`	Whether the company is active
`createdAt`	`string`	ISO 8601 creation timestamp

Create a company

POST /v1/companies

Registers a new company under your account. The VAT number format is validated against the country’s rules.

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Legal company name
`vatNumber`	`string`	Yes	VAT number with country prefix (e.g., `RO12345678`)
`country`	`string`	Yes	ISO 3166-1 alpha-2 code (`RO`, `IT`, `BE`, `PL`, `FR`, `DE`)
`registrationNumber`	`string`	No	Trade register / company registration number
`address`	`object`	No	Company address (see below)
`currency`	`string`	No	Default currency (defaults to `EUR`)
`contacts`	`object`	No	Contact details (see below)

Address object

Field	Type	Required	Description
`street`	`string`	No	Street address
`city`	`string`	No	City
`postalCode`	`string`	No	Postal code
`country`	`string`	Yes	ISO 3166-1 alpha-2 country code
`stateOrProvince`	`string`	No	State, province, or county

Contacts object

Field	Type	Required	Description
`email`	`string`	No	Contact email address
`phone`	`string`	No	Contact phone number

Example request

curl -X POST https://api.getmandato.dev/v1/companies \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TechVision SRL",
    "vatNumber": "RO12345678",
    "country": "RO",
    "registrationNumber": "J40/1234/2020",
    "address": {
      "street": "Strada Exemplu 42",
      "city": "Bucharest",
      "postalCode": "010101",
      "country": "RO"
    },
    "currency": "RON",
    "contacts": {
      "email": "billing@techvision.ro",
      "phone": "+40712345678"
    }
  }'

Example response (201 Created)

{
  "data": {
    "id": "comp_a1b2c3d4e5f6",
    "name": "TechVision SRL",
    "vatNumber": "RO12345678",
    "country": "RO",
    "currency": "RON",
    "isActive": true,
    "createdAt": "2025-01-10T09:00:00.000Z"
  }
}

Error responses

Status	Type	Description
`400`	`validation_error`	Invalid VAT number format, missing fields, etc.
`403`	`limit_exceeded`	Maximum company limit reached for your plan

List companies

GET /v1/companies

Returns all companies for your account.

Example request

curl https://api.getmandato.dev/v1/companies \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": [
    {
      "id": "comp_a1b2c3d4e5f6",
      "name": "TechVision SRL",
      "vatNumber": "RO12345678",
      "country": "RO",
      "currency": "RON",
      "isActive": true,
      "createdAt": "2025-01-10T09:00:00.000Z"
    },
    {
      "id": "comp_f6e5d4c3b2a1",
      "name": "TechVision Italia S.r.l.",
      "vatNumber": "IT12345678901",
      "country": "IT",
      "currency": "EUR",
      "isActive": true,
      "createdAt": "2025-01-12T14:30:00.000Z"
    }
  ]
}

Get a company

GET /v1/companies/:id

Retrieves a single company by ID.

Path parameters

Parameter	Type	Description
`id`	`string`	Company ID (e.g., `comp_a1b2c3d4e5f6`)

Example request

curl https://api.getmandato.dev/v1/companies/comp_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": {
    "id": "comp_a1b2c3d4e5f6",
    "name": "TechVision SRL",
    "vatNumber": "RO12345678",
    "country": "RO",
    "currency": "RON",
    "isActive": true,
    "createdAt": "2025-01-10T09:00:00.000Z"
  }
}

Error responses

Status	Type	Description
`404`	`not_found`	Company not found or belongs to a different account

Update a company

PATCH /v1/companies/:id

Updates a company’s mutable fields. The vatNumber and country cannot be changed after creation — create a new company instead.

Path parameters

Parameter	Type	Description
`id`	`string`	Company ID

Request body

All fields are optional. Only include the fields you want to update.

Field	Type	Description
`name`	`string`	Updated company name
`address`	`object`	Updated address
`currency`	`string`	Updated default currency
`contacts`	`object`	Updated contact details

Example request

curl -X PATCH https://api.getmandato.dev/v1/companies/comp_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TechVision Romania SRL",
    "contacts": {
      "email": "invoices@techvision.ro"
    }
  }'

Example response

{
  "data": {
    "id": "comp_a1b2c3d4e5f6",
    "name": "TechVision Romania SRL",
    "vatNumber": "RO12345678",
    "country": "RO",
    "currency": "RON",
    "isActive": true,
    "createdAt": "2025-01-10T09:00:00.000Z"
  }
}

Error responses

Status	Type	Description
`400`	`validation_error`	Invalid field values
`404`	`not_found`	Company not found or belongs to a different account

Delete a company

DELETE /v1/companies/:id

Soft-deletes a company. The company is marked as inactive and can no longer be used for new invoices. Existing invoices are not affected.

Path parameters

Parameter	Type	Description
`id`	`string`	Company ID

Example request

curl -X DELETE https://api.getmandato.dev/v1/companies/comp_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": {
    "id": "comp_a1b2c3d4e5f6",
    "deleted": true
  }
}

Error responses

Status	Type	Description
`404`	`not_found`	Company not found or belongs to a different account