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_KEYenvironment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). - Read Manage contacts for how contacts become parties.
Add a company signatory
Find or create the company
Filter the company list by organization number first. The filter matches exactly and ignores a hyphen:
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:
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:
{
"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.
Link a contact to the company
Create the contact with companyId and the person's companyRole, or send them in a PATCH request to an existing contact:
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.
Add the contact as a company party
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:
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", "signatureMethod": "SE_BANKID" }
]
}'Replace CONTACT_ID with the contact id. Without a contact, send name, email, and a company object on the party instead:
{
"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.
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:
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.
List and get companies
GET /api/v1/companieslists companies, newest first.querymatches part of the name or organization number, andorgNumberandnamematch exactly. Every filter you pass must match. The response has the companies indata; whilehasMoreistrue, passnextCursorascursorto get the next page. For more information, see Pagination.GET /api/v1/companies/COMPANY_IDreturns the company. To list its contacts, callGET /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:nameis missing, or a party hascompany.namewithoutcompany.orgNumber.409 ALREADY_EXISTS: a company with the organization number exists. Use the existing one from the list.404 NOT_FOUNDfromcompany-registry: the registry has no company with the organization number.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on