Contacts
Reusable records of the people and companies you send documents to
A contact is a person you send documents to more than once. A company groups contacts who work for the same organization. Both belong to a workspace.
When you add a contact to a document, sajn creates a party from it. The party takes a copy of the contact's details, so a later change to the contact doesn't change documents you already created.
flowchart LR
company["Company<br/>Example AB"] --- contact["Contact<br/>Kai Berg"]
contact -- "contactId" --> party1["Party on document 1"]
contact -- "contactId" --> party2["Party on document 2"]Contact fields
| Field | Required | Description |
|---|---|---|
firstName | Yes | First name |
lastName | No | Last name |
email | No | Email address, for email delivery |
phone | No | Phone number, for SMS delivery and SMS verification |
nationalId | No | National identity number, such as a Swedish personnummer. sajn compares it with the eID at signing. In API version 2026-09, this field is ssn. |
companyId | No | The company the contact works for |
companyRole | No | The contact's role at the company, such as CEO |
externalId | No | Your own ID for the contact, such as a CRM record ID |
addressLine1, addressLine2, postalCode, city, state, country | No | Postal address. country is an ISO 3166-1 alpha-2 code, such as SE. |
The following request body creates a contact:
{
"firstName": "Kai",
"lastName": "Berg",
"email": "kai@example.com",
"phone": "+46705550123",
"companyId": "cm4k2x9p70009abcd6789cdef",
"companyRole": "CEO",
"externalId": "crm-10422"
}To create it, send the body to POST /contacts. The response is the contact, with the full company in company.
Companies
A company has a name, an optional orgNumber, and an optional country. To link a contact to a company, set the contact's companyId. To read a company, call GET /companies/{id}, and to list its contacts, call GET /contacts?companyId=. To find companies, filter GET /companies by orgNumber or name.
To find a company's details in the business registry by its organization number, call GET /company-registry/{orgNumber}.
Use a contact on a document
To add a contact as a party, send its contactId, either in parties when you create the document, or to POST /documents/{id}/parties:
{
"contactId": "cm4k2x9p40006abcd3456qrst",
"role": "SIGNER",
"signatureMethod": "SE_BANKID"
}The party gets the contact's name, email, phone number, national ID, and company. The party's contactId links back to the contact.
Find contacts
To list contacts, call GET /contacts. Use query to search first name, last name, email, phone, and company. To filter, pass email, phone, externalId, companyId, or tagId; a contact must match every filter you pass. For pagination, see Pagination.
Before you create a contact, look it up by email or externalId, so you don't create duplicates. If you sync contacts from another system, store that system's ID in externalId.
Delete a contact
DELETE /contacts/{id} deletes a contact permanently and returns its id with deleted set to true. Parties created from the contact keep their own copy of its details and are unlinked from it, so existing documents don't change.
Next steps
Was this page helpful?
Last updated on