Managing Contacts

Contacts are reusable records of individuals you frequently send documents to. By managing contacts effectively, you can speed up document creation and maintain consistent signer information across your organization.

Why Use Contacts?

Instead of manually entering signer details each time you create a document, contacts allow you to:

Save time by reusing stored information
Reduce errors with pre-validated contact details
Track history across all documents a person has signed
Stay organized by linking contacts to companies

Contacts list in the sajn dashboard showing a searchable list of individuals

Creating Contacts

Individual Contacts

Create a contact with the essential information for document delivery:

curl -X POST https://app.sajn.se/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Anna",
    "lastName": "Andersson",
    "email": "[email protected]",
    "phone": "+46701234567"
  }'

Response:

{
  "contact": {
    "id": "contact_abc123",
    "firstName": "Anna",
    "lastName": "Andersson",
    "email": "[email protected]",
    "phone": "+46701234567",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Create contact form in sajn showing fields for name, email, and phone

Contact Fields

Field	Required	Description
`firstName`	Yes	Contact’s first name
`lastName`	Yes	Contact’s last name
`email`	No	Email address for document delivery
`phone`	No	Phone number for SMS delivery
`ssn`	No	Swedish personal number (personnummer)
`companyId`	No	Link to an existing company
`companyRole`	No	Role within the company (e.g., “CEO”, “CFO”)
`externalId`	No	Your system’s identifier for integration

At least one of email or phone is recommended so documents can be delivered to the contact.

Contacts with Company Association

Link a contact to an existing company:

{
  "firstName": "Erik",
  "lastName": "Eriksson",
  "email": "[email protected]",
  "companyId": "company_xyz789",
  "companyRole": "CFO"
}

Searching and Filtering Contacts

List All Contacts

Retrieve a paginated list of all contacts in your organization:

curl -X GET "https://app.sajn.se/api/v1/contacts?page=1&perPage=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search by Specific Criteria

Search for contacts by email, phone, or external ID:

# Search by email
curl -X GET "https://app.sajn.se/api/v1/contacts/[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by phone
curl -X GET "https://app.sajn.se/api/v1/contacts/search?phone=+46701234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by external ID
curl -X GET "https://app.sajn.se/api/v1/contacts/search?externalId=customer_456" \
  -H "Authorization: Bearer YOUR_API_KEY"

All searches are exact matches scoped to your organization. The search returns an array of matching contacts, or an empty array if no matches are found.

Linking Contacts to Signers

When creating a document, reference an existing contact instead of manually entering signer details:

curl -X POST https://app.sajn.se/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "type": "SIGNABLE",
    "signers": [
      {
        "contactId": "contact_abc123",
        "role": "SIGNER",
        "signingOrder": 1,
        "deliveryMethod": "EMAIL",
        "requiredSignature": "BANKID"
      }
    ]
  }'

The signer automatically inherits the contact’s name, email, and phone number. You can still override specific fields if needed:

{
  "contactId": "contact_abc123",
  "email": "[email protected]",
  "role": "SIGNER",
  "signingOrder": 1,
  "deliveryMethod": "EMAIL",
  "requiredSignature": "DRAWING"
}

Updating Contacts

Update an existing contact’s information:

curl -X PATCH https://app.sajn.se/api/v1/contacts/contact_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "phone": "+46709876543"
  }'

Updating a contact does not affect existing document signers. Changes only apply to new documents created with this contact.

Deleting Contacts

Remove a contact from your organization:

curl -X DELETE https://app.sajn.se/api/v1/contacts/contact_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleted contacts are soft-deleted to preserve historical data. They are hidden from lists, but existing document references remain valid for audit purposes.

Best Practices

Check for duplicates before creating

Use the search endpoint to check if a contact already exists before creating a new one. This prevents duplicate records and maintains data quality.

# Check if contact exists before creating
curl -X GET "https://app.sajn.se/api/v1/contacts/[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use external IDs for integration

When integrating with a CRM or other system, always set externalId to your system’s identifier. This makes syncing and lookups straightforward.

Keep contact information current

Regularly update contact details, especially email addresses and phone numbers, to ensure successful document delivery.

Organize with companies

For B2B scenarios, create companies and link contacts to them. This improves organization and makes it easier to find all contacts from a specific organization.

Validate data before creation

Ensure email addresses are valid and phone numbers are in international format (e.g., +46701234567) before creating contacts.

Next Steps

Working with Companies

Learn how to create and manage company records

Creating Documents

Use contacts when creating documents

Contacts API

Explore the full Contacts API reference

Signers Concept

Understand how signers work in sajn

​Managing Contacts

​Why Use Contacts?

​Creating Contacts

​Individual Contacts

​Contact Fields

​Contacts with Company Association

​Searching and Filtering Contacts

​List All Contacts

​Search by Specific Criteria

​Linking Contacts to Signers

​Updating Contacts

​Deleting Contacts

​Best Practices

​Next Steps

Working with Companies

Creating Documents

Contacts API

Signers Concept

Managing Contacts

Why Use Contacts?

Creating Contacts

Individual Contacts

Contact Fields

Contacts with Company Association

Searching and Filtering Contacts

List All Contacts

Search by Specific Criteria

Linking Contacts to Signers

Updating Contacts

Deleting Contacts

Best Practices

Next Steps