Managing Contacts

Learn how to create, organize, and manage contacts for efficient document signing workflows

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

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": "[e-mail]",
    "phone": "[phone]"
  }'

Response:

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

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": "[e-mail]",
  "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/search?email=[e-mail]" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by phone
curl -X GET "https://app.sajn.se/api/v1/contacts/search?phone=[phone]" \
  -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": "[e-mail]",
  "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": "[e-mail]",
    "phone": "[phone]"
  }'

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/search?email=[e-mail]" \
  -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., [phone]) 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