> ## 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.

# 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_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

<Steps>
  <Step title="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:

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Create the contact">
    If no contact matched, send a `POST` request to `/api/v1/contacts`. Only `firstName` is required:

    ```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": "Alex",
        "lastName": "Andersson",
        "email": "alex@example.com",
        "phone": "+46700000000",
        "externalId": "crm-4711"
      }'
    ```

    The response is the contact:

    ```json theme={null}
    {
      "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](/guides/contacts/working-with-companies). `nationalId`, such as a Swedish personal identity number, lets an eID check the person's identity at signing.
  </Step>

  <Step title="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:

    ```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": "Service agreement",
        "templateId": "TEMPLATE_ID",
        "parties": [
          { "contactId": "CONTACT_ID", "role": "SIGNER", "deliveryMethod": "SMS", "requiredSignature": "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`.
  </Step>
</Steps>

## 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](/api-fundamentals/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](/api-fundamentals/errors).

## Next steps

<CardGroup cols={2}>
  <Card title="Work with companies" icon="building" href="/guides/contacts/working-with-companies">
    Link contacts to companies and sign on their behalf.
  </Card>

  <Card title="Parties" icon="users" href="/concepts/parties">
    Learn how parties relate to contacts.
  </Card>

  <Card title="Contacts" icon="address-book" href="/concepts/contacts">
    Learn how contacts work.
  </Card>

  <Card title="Create a new contact" icon="code" href="/api-reference/create-a-new-contact">
    See the contact endpoints in the API reference.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.