> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sajn.se/llms.txt
> Use this file to discover all available pages before exploring further.
# Work with companies
> Keep company records, link contacts to them, and add parties who sign on behalf of a company
In this guide, you create a company record, link a contact to it, and add that contact to a document as a party who signs on behalf of the company. A company party's name, company name, and organization number appear on the document and in the signing certificate.
## Before you begin
* Store your API key in the `SAJN_API_KEY` environment variable. To create a key, go to workspace settings in the sajn app, then **Utvecklare** (Developer) > **API-nycklar** (API keys).
* Read [Manage contacts](/guides/contacts/managing-contacts) for how contacts become parties.
## Add a company signatory
Filter the company list by organization number first. The filter matches exactly and ignores a hyphen:
```bash theme={null}
curl "https://app.sajn.se/api/v1/companies?orgNumber=556000-0000" \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"
```
If the response's `data` array is empty, create the company:
```bash theme={null}
curl -X POST https://app.sajn.se/api/v1/companies \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{ "name": "Example AB", "orgNumber": "556000-0000", "country": "SE" }'
```
The response is the company:
```json theme={null}
{
"id": "cm4k2xk9z0011abcd6802stuv",
"name": "Example AB",
"orgNumber": "556000-0000",
"country": "SE",
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z"
}
```
`country` is an ISO 3166-1 alpha-2 country code and defaults to `SE`. Organization numbers are unique in the organization: creating a second company with the same number returns `409 ALREADY_EXISTS`.
Create the contact with `companyId` and the person's `companyRole`, or send them in a `PATCH` request to an existing contact:
```bash theme={null}
curl -X POST https://app.sajn.se/api/v1/contacts \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Kai",
"lastName": "Berg",
"email": "kai@example.com",
"companyId": "COMPANY_ID",
"companyRole": "CEO"
}'
```
Replace `COMPANY_ID` with the company `id`. The response is the contact, with the company in `company`.
Reference the contact in a document's `parties`. The party gets the person's details and the company's name and organization number, so its `type` is `COMPANY`:
```bash theme={null}
curl -X POST https://app.sajn.se/api/v1/documents \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Supplier agreement - Example AB",
"templateId": "TEMPLATE_ID",
"parties": [
{ "contactId": "CONTACT_ID", "role": "SIGNER", "requiredSignature": "SE_BANKID" }
]
}'
```
Replace `CONTACT_ID` with the contact `id`. Without a contact, send `name`, `email`, and a `company` object on the party instead:
```json theme={null}
{
"name": "Kai Berg",
"email": "kai@example.com",
"role": "SIGNER",
"company": { "name": "Example AB", "orgNumber": "556000-0000", "role": "CEO" }
}
```
Send `company.name` and `company.orgNumber` together or not at all. On the document, each party has its company in `company`, or `null` for a private individual. Template parties nest their company in `company` the same way. For more information, see [Manage templates](/guides/templates/managing-templates).
## Look up a company in the registry
To prefill a company from the external company registry, send a `GET` request to `/api/v1/company-registry/ORG_NUMBER`:
```bash theme={null}
curl https://app.sajn.se/api/v1/company-registry/5560000000 \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"
```
Replace `ORG_NUMBER` with the organization number, with or without a hyphen. The response has the company's basic details, with the organization number in `basic.orgNumber`, its address, legal form, VAT registration, business activity, signature rule, and the responsible persons, such as executives and board members. Results are cached for three days. The endpoint doesn't create a company record; send a `POST` request to `/api/v1/companies` for that. For the full response, see [Look up a company in the company registry](/api-reference/look-up-a-company-in-the-company-registry).
## List and get companies
* `GET /api/v1/companies` lists companies, newest first. `query` matches part of the name or organization number, and `orgNumber` and `name` match exactly. Every filter you pass must match. The response has the companies in `data`; while `hasMore` is `true`, pass `nextCursor` as `cursor` to get the next page. For more information, see [Pagination](/api-fundamentals/pagination).
* `GET /api/v1/companies/COMPANY_ID` returns the company. To list its contacts, call `GET /api/v1/contacts?companyId=COMPANY_ID`.
## Choose between a company party and an individual party
A company party signs as a representative of the company, and the document shows both their name and the company. An individual party signs for themselves. When a person signs both for the company and personally, such as a CEO who also gives a personal guarantee, add them as two parties.
To see who can sign for a Swedish company, read the signature rule from the registry lookup.
## Handle errors
* `400 VALIDATION_FAILED`: `name` is missing, or a party has `company.name` without `company.orgNumber`.
* `409 ALREADY_EXISTS`: a company with the organization number exists. Use the existing one from the list.
* `404 NOT_FOUND` from `company-registry`: the registry has no company with the organization number.
For the error shape and every code, see [Errors](/api-fundamentals/errors).
## Next steps
Sync people into sajn contacts.
Require an eID for company signatories.
See the company endpoints in the API reference.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.