Manage contacts
Keep a contact for each person you send documents to, find it by email or external ID, and add it to documents as a party
In this guide, you sync people from your system into sajn contacts and add them to documents as parties. A contact holds a person's name, email address, phone number, and company once, so you don't repeat them on every document. A party added from a contact copies its details and keeps a link to it in contactId.
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).
Sync a person and add them to a document
Look for an existing contact
To avoid duplicates, filter the contact list by your own ID or by email address before you create a contact. These filters match exactly:
curl "https://app.sajn.se/api/v1/contacts?externalId=crm-4711" \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"The response has the matching contacts in data, which is empty when nothing matches. The list also takes email and phone. When you pass several filters, a contact must match all of them. Encode a leading + in a phone number as %2B.
Create the contact
If no contact matched, send a POST request to /api/v1/contacts. Only firstName is required:
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": "Alex",
"lastName": "Andersson",
"email": "alex@example.com",
"phone": "+46700000000",
"externalId": "crm-4711"
}'The response is the contact:
{
"id": "cm4k2xb7q0003abcd9012mnop",
"firstName": "Alex",
"lastName": "Andersson",
"email": "alex@example.com",
"phone": "+46700000000",
"nationalId": null,
"externalId": "crm-4711",
"addressLine1": null,
"addressLine2": null,
"postalCode": null,
"city": null,
"state": null,
"country": null,
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z",
"companyRole": null,
"company": null
}To store the person's address, send addressLine1, addressLine2, postalCode, city, state, and country. To link the contact to a company, send companyId and companyRole. For more information, see Work with companies. nationalId, such as a Swedish personal identity number, lets an eID check the person's identity at signing.
Add the contact to a document
Reference the contact with contactId in a document's parties. The party gets the contact's name, email address, phone number, and 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": "Service agreement",
"templateId": "TEMPLATE_ID",
"parties": [
{ "contactId": "CONTACT_ID", "role": "SIGNER", "delivery": ["SMS"], "signatureMethod": "SE_BANKID" }
]
}'Replace CONTACT_ID with the contact id. Because the contact has a phone number, the party can get the invitation by SMS. To add the contact to an existing draft, send contactId to POST /api/v1/documents/DOCUMENT_ID/parties.
List, update, and delete contacts
- List contacts with
GET /api/v1/contacts.querysearches names, email addresses, phone numbers, and companies.email,phone,externalId,companyId, andtagIdfilter, and every filter you pass must match. To sync changes, passupdatedAfter. The response has the contacts indata; whilehasMoreistrue, passnextCursorascursorto get the next page. For more information, see Pagination. - Update a contact with
PATCH /api/v1/contacts/CONTACT_ID, sending only the fields to change.nullclearsemail,phone,nationalId,externalId, orcompanyRole. Parties already on documents keep the details they were created with. - Delete a contact with
DELETE /api/v1/contacts/CONTACT_ID. The deletion is permanent, and the response is{ "id": "CONTACT_ID", "deleted": true }. Parties created from the contact stay on their documents with their own copy of the details, unlinked from the contact.
Handle errors
400 VALIDATION_FAILED:firstNameis missing oremailisn't a valid address.404 NOT_FOUND: no contact in the workspace has the ID, including acontactIdin a document'sparties.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on