Company Management

A company represents a Polish business entity (identified by NIP) that submits invoices to KSeF. Companies belong to a tenant — when you authenticate, you can only see companies in your tenant.

Tenant (e.g. "Accounting Firm ABC")
  ├── Company: "Bizneto" (NIP: 8133793363)
  │     ├── Credentials (KSeF tokens, certificates)
  │     ├── Sessions (KSeF authentication)
  │     └── Invoices
  └── Company: "Client XYZ Sp. z o.o." (NIP: 5261040828)
        ├── Credentials
        └── Invoices

Typical flow: Create company → Add KSeF credentials (Tokens & Certificates) → Open session (Sessions) → Submit invoices (Invoice Submission)

Register Company

POST /api/companies
Authorization: Bearer {token}
Content-Type: application/json

Request:

{
  "nip": "5261040828",
  "name": "Test Docs Company Sp. z o.o.",
  "address": {
    "street": "ul. Dokumentowa 10",
    "city": "Warszawa",
    "postal_code": "00-100",
    "country": "PL"
  },
  "contact": {
    "email": "[email protected]",
    "phone": "+48123456789"
  }
}

Field	Type	Required	Description
`nip`	string	✅	Polish tax ID, exactly 10 digits
`name`	string	✅	Legal company name
`address.street`	string	✅	Street and number
`address.city`	string	✅	City
`address.postal_code`	string	✅	Format: `XX-XXX`
`address.country`	string	❌	ISO 3166-1 alpha-2, defaults to `PL`
`contact.email`	string	✅	Contact email
`contact.phone`	string	❌	Phone, e.g. `+48123456789`

Response (201 Created):

{
  "nip": "5261040828",
  "name": "Test Docs Company Sp. z o.o.",
  "address": {
    "street": "ul. Dokumentowa 10",
    "city": "Warszawa",
    "postal_code": "00-100",
    "country": "PL"
  },
  "contact": {
    "email": "[email protected]",
    "phone": "+48123456789"
  },
  "company_id": "0e727e62-7acb-49e8-942e-d4d33b758b09",
  "status": "active",
  "created_at": "2026-03-14T12:22:12.697954Z",
  "updated_at": null
}

The company_id UUID is used in all subsequent operations — save it. The nip must be unique within your tenant.

List Companies

GET /api/companies
Authorization: Bearer {token}

Returns all companies in your tenant (filtered automatically by row-level security).

Response (200):

[
  {
    "company_id": "22919080-f3fe-4aff-8d71-f6493afc956a",
    "nip": "8133793363",
    "name": "Bizneto",
    "status": "active",
    "created_at": "2026-03-11T22:20:23.141677Z"
  }
]

Get Company

GET /api/companies/{company_id}
Authorization: Bearer {token}

Returns the full company object. Returns 403 (not 404) if the company doesn't exist or belongs to a different tenant — this is by design for security, as row-level security makes other tenants' companies invisible.

Update Company

PUT /api/companies/{company_id}
Authorization: Bearer {token}
Content-Type: application/json

Request (partial update):

{
  "name": "Test Docs Company (Updated)",
  "contact": {
    "email": "[email protected]",
    "phone": "+48987654321"
  }
}

Field	Type	Required	Description
`name`	string	❌	New company name
`address`	object	❌	New address (full object)
`contact`	object	❌	New contact (full object)
`status`	string	❌	`active` or `inactive`

NIP cannot be changed after creation. To change NIP, delete the company and create a new one.

Delete Company (Soft Delete)

DELETE /api/companies/{company_id}
Authorization: Bearer {token}

Response: 204 No Content

The company is not physically removed — its status is set to inactive. All data (invoices, credentials, sessions) is preserved for audit purposes. To reactivate, use PUT with {"status": "active"}.

Error Responses

HTTP	Error	Cause
400	`Company with NIP already exists`	Duplicate NIP in your tenant
401	`Not authenticated`	Missing or invalid JWT
403	`Access denied to this company`	Company not found or wrong tenant
422	Validation error	Missing required fields or NIP too short

Important Notes

NIP validation: The API validates NIP length (10 digits) but does not verify it against REGON/VIES. Ensure you use a valid, registered NIP — KSeF will reject invoices with invalid seller NIP.

NIP ↔ Invoice link: When submitting invoices, the Podmiot1/NIP in FA(3) XML must match the company's NIP.

Tenant isolation: Companies are scoped to your tenant via PostgreSQL row-level security. You cannot access companies from other tenants.

Endpoint Reference

Method	Endpoint	Role	Description
`POST`	`/api/companies`	admin	Register new company
`GET`	`/api/companies`	viewer	List all companies in tenant
`GET`	`/api/companies/{company_id}`	viewer	Get single company
`PUT`	`/api/companies/{company_id}`	admin	Update company
`DELETE`	`/api/companies/{company_id}`	admin	Soft delete (set inactive)

Company Management

On this page