Skip to main content
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_KEY environment 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

1

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:
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.
2

Create the contact

If no contact matched, send a POST request to /api/v1/contacts. Only firstName is required:
The response is the contact:
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.
3

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:
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. query searches names, email addresses, phone numbers, and companies. email, phone, externalId, companyId, and tagId filter, and every filter you pass must match. To sync changes, pass updatedAfter. The response has the contacts in data; while hasMore is true, pass nextCursor as cursor to 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. null clears email, phone, nationalId, externalId, or companyRole. 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: firstName is missing or email isn’t a valid address.
  • 404 NOT_FOUND: no contact in the workspace has the ID, including a contactId in a document’s parties.
For the error shape and every code, see Errors.

​
Next steps

Work with companies

Link contacts to companies and sign on their behalf.

Parties

Learn how parties relate to contacts.

Contacts

Learn how contacts work.

Create a new contact

See the contact endpoints in the API reference.