Custom Fields

Custom fields allow you to attach structured metadata to documents beyond the standard fields. Define your own fields to track project codes, departments, cost centers, or any other information relevant to your workflow.

Why Use Custom Fields?

Custom fields provide a way to:

Add structured data that your business needs to track
Enable filtering and reporting by custom criteria
Integrate with external systems using consistent data formats
Enforce data standards with validation rules

Custom fields configuration screen showing different field types

Creating Custom Field Definitions

Before adding custom field values to documents, you must create field definitions that specify the field name, type, and validation rules.

curl -X POST https://app.sajn.se/api/v1/custom-fields \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Code",
    "key": "project_code",
    "type": "TEXT",
    "required": false,
    "description": "Internal project identifier"
  }'

Response:

{
  "customField": {
    "id": "cf_abc123",
    "name": "Project Code",
    "key": "project_code",
    "type": "TEXT",
    "required": false,
    "description": "Internal project identifier",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Field Definition Properties

Property	Required	Description
`name`	Yes	Display name shown in the UI
`key`	Yes	Unique identifier used in API calls
`type`	Yes	Data type (see Field Types below)
`required`	No	Whether the field must have a value
`description`	No	Help text explaining the field’s purpose
`options`	No	For SELECT type, the available choices

Field Types

Text Fields

For free-form text input:

{
  "name": "Reference Number",
  "key": "reference_number",
  "type": "TEXT"
}

Number Fields

For numeric values:

{
  "name": "Contract Value",
  "key": "contract_value",
  "type": "NUMBER"
}

Date Fields

For date values:

{
  "name": "Start Date",
  "key": "start_date",
  "type": "DATE"
}

Select Fields

For predefined choices:

{
  "name": "Department",
  "key": "department",
  "type": "SELECT",
  "options": [
    { "value": "hr", "label": "Human Resources" },
    { "value": "legal", "label": "Legal" },
    { "value": "sales", "label": "Sales" },
    { "value": "finance", "label": "Finance" }
  ]
}

Document detail view showing custom field values

Setting Custom Field Values on Documents

When Creating a Document

Include custom field values in the document creation request:

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 - Project Alpha",
    "type": "SIGNABLE",
    "customFields": [
      {
        "customInputId": "cf_abc123",
        "value": "PROJ-2024-001"
      },
      {
        "customInputId": "cf_def456",
        "value": "legal"
      },
      {
        "customInputId": "cf_ghi789",
        "value": "150000"
      }
    ]
  }'

Using Field Keys

You can also reference custom fields by their key:

{
  "name": "Vendor Contract",
  "type": "SIGNABLE",
  "customFields": [
    {
      "key": "project_code",
      "value": "PROJ-2024-002"
    },
    {
      "key": "department",
      "value": "sales"
    }
  ]
}

Updating Custom Field Values

Update custom field values on an existing document:

curl -X PATCH https://app.sajn.se/api/v1/documents/doc_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customFields": [
      {
        "customInputId": "cf_abc123",
        "value": "PROJ-2024-001-UPDATED"
      }
    ]
  }'

Querying Documents by Custom Fields

Filter documents based on custom field values:

# Find all documents with a specific project code
curl -X GET "https://app.sajn.se/api/v1/documents?customField.project_code=PROJ-2024-001" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Find all documents for the Legal department
curl -X GET "https://app.sajn.se/api/v1/documents?customField.department=legal" \
  -H "Authorization: Bearer YOUR_API_KEY"

Managing Custom Field Definitions

Listing All Custom Fields

curl -X GET https://app.sajn.se/api/v1/custom-fields \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "customFields": [
    {
      "id": "cf_abc123",
      "name": "Project Code",
      "key": "project_code",
      "type": "TEXT",
      "required": false
    },
    {
      "id": "cf_def456",
      "name": "Department",
      "key": "department",
      "type": "SELECT",
      "required": true,
      "options": [
        { "value": "hr", "label": "Human Resources" },
        { "value": "legal", "label": "Legal" }
      ]
    }
  ]
}

Updating a Custom Field Definition

curl -X PATCH https://app.sajn.se/api/v1/custom-fields/cf_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Reference",
    "description": "Updated description for project codes"
  }'

Deleting a Custom Field Definition

curl -X DELETE https://app.sajn.se/api/v1/custom-fields/cf_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting a custom field definition removes all values associated with that field from all documents. This action cannot be undone.

Common Use Cases

Project Tracking

Track documents by project for easy reporting:

{
  "name": "Project Code",
  "key": "project_code",
  "type": "TEXT",
  "required": true,
  "description": "Format: PROJ-YYYY-NNN"
}

Department Assignment

Assign documents to departments:

{
  "name": "Department",
  "key": "department",
  "type": "SELECT",
  "required": true,
  "options": [
    { "value": "hr", "label": "Human Resources" },
    { "value": "legal", "label": "Legal" },
    { "value": "sales", "label": "Sales" },
    { "value": "finance", "label": "Finance" },
    { "value": "it", "label": "IT" }
  ]
}

Cost Center Tracking

Track documents for financial allocation:

{
  "name": "Cost Center",
  "key": "cost_center",
  "type": "TEXT",
  "required": false,
  "description": "Financial cost center code"
}

Contract Value

Record monetary values for contracts:

{
  "name": "Contract Value (SEK)",
  "key": "contract_value",
  "type": "NUMBER",
  "required": false
}

Renewal Date

Track contract renewal dates:

{
  "name": "Renewal Date",
  "key": "renewal_date",
  "type": "DATE",
  "required": false,
  "description": "Date when contract is up for renewal"
}

Best Practices

Plan your field structure

Before creating custom fields, plan what data you need to track. Consider how fields will be used for filtering, reporting, and integration.

Use consistent naming conventions

Use clear, descriptive names and consistent key formats. For example, use snake_case for keys: project_code, cost_center.

Choose appropriate field types

Use the right field type for your data: TEXT for free-form input, SELECT for controlled vocabularies, NUMBER for numeric values, DATE for dates.

Add helpful descriptions

Include descriptions that explain the field’s purpose and expected format. This helps users enter correct values.

Mark essential fields as required

For fields that are critical to your workflow, set required: true. This ensures documents always have the necessary metadata.

Keep SELECT options manageable

For SELECT fields, limit options to a reasonable number. If you have too many options, consider using a TEXT field instead.

Next Steps

Organizing with Tags

Categorize documents with tags

Creating Documents

Add custom fields when creating documents

Custom Fields API

Explore the full Custom Fields API reference

Webhooks

Receive notifications with custom field data

​Custom Fields

​Why Use Custom Fields?

​Creating Custom Field Definitions

​Field Definition Properties

​Field Types

​Text Fields

​Number Fields

​Date Fields

​Select Fields

​Setting Custom Field Values on Documents

​When Creating a Document

​Using Field Keys

​Updating Custom Field Values

​Querying Documents by Custom Fields

​Managing Custom Field Definitions

​Listing All Custom Fields

​Updating a Custom Field Definition

​Deleting a Custom Field Definition

​Common Use Cases

​Project Tracking

​Department Assignment

​Cost Center Tracking

​Contract Value

​Renewal Date

​Best Practices

​Next Steps

Organizing with Tags

Creating Documents

Custom Fields API

Webhooks

Custom Fields

Why Use Custom Fields?

Creating Custom Field Definitions

Field Definition Properties

Field Types

Text Fields

Number Fields

Date Fields

Select Fields

Setting Custom Field Values on Documents

When Creating a Document

Using Field Keys

Updating Custom Field Values

Querying Documents by Custom Fields

Managing Custom Field Definitions

Listing All Custom Fields

Updating a Custom Field Definition

Deleting a Custom Field Definition

Common Use Cases

Project Tracking

Department Assignment

Cost Center Tracking

Contract Value

Renewal Date

Best Practices

Next Steps