Documents are managed by Socotra with a system of events, data, rendering, and storage. This guide describes how they are created and managed.

Document Types

There are two main kinds of documents that Socotra handles:

  • Dynamic documents are rendered on demand based on event data and a trigger.

  • Static documents are PDF files. Copies of each document are attached as needed. Static documents can be stored either in your configuration files or independently.

Rendering Targets

Dynamic documents can be rendered to either Portable Document Format (PDF), or raw HTML. The specific target is based on the configuration preference, on the type field.


Document templates are configured at the policy level in the configuration. Any template that is capable of consuming and using the data for the triggering event can be associated with that event. Each template is stored with a .template.liquid extension.

For a complete overview of how to author document templates, see the document templates configuration guide.

Triggering events

The following events can trigger a document:

  • Policy quotation, finalization, and issuance

  • Endorsement quotation and acceptance

  • Renewal quotation and acceptance

  • Invoice issuance

  • Premium Report issuance

  • Grace Period start

  • Policy Cancellation (based on lapse or manual cancellation)

  • Reinstatement

Document Attachment

Most documents are attached to their parent object at the time of rendering. For endorsements and renewals, documents are rendered and associated with the endorsement or renewal object based on the generatingEvent, but after the transaction is issued the documents are also attached to the parent policy.

Documents can also be added to a policy, or removed from a policy, with the add document and remove document endpoints.


For each event trigger, a document, or for some triggers multiple documents may be specified to render. For each one you can select the following:

  • Document Type (PDF or HTML)

  • The document template name

  • The filename for storing the document

  • The display name for the documents

  • The layout, including page size, orientation, and margin sizes

Some triggers also support a generatingEvent property. For example, for documents created with a new policy, you can select whether each one is generated with the quote, accept, or issue events.

Document Layouts

The margins, paper size, and orientation for documents have the following default values:

  • Page Size: 8.5 inches (215.9mm) wide and 11 inches (279.4mm) tall

  • Orientation: Portrait

  • Left Margin: 1 inch (25.4mm)

  • Right Margin: 1 inch (25.4mm)

  • Top Margin: 1 inch (25.4mm), unless a header is defined for the document, in which case it will be 1.39 inches (35.4mm)

  • Bottom Margin: 1 inch (25.4mm), unless a footer is defined for the document, in which case it will be 1.3.9 inches (35.4mm)

Each of these settings can be overridden on a per-document-template basis. The following values are allowed for the various layout properties:

  • marginLeft, marginRight, marginTop, or marginBottom: number from 0 to 100, with 0.1 increments. These values are in millimeters (mm).

  • pageSize: Any of Letter, Legal, Tabloid, A3, A4, A5, B4, or B5

  • orientation: Either of Portrait or Landscape

If a value is not specified, the default as specified above will be used.

To change document layout preferences, set the DocumentPageLayout values in the configuration for the document. For example, the configuration for a document could look like this:

  // omitted lots of properties
  "documents": [
      "displayName": "My Document",
      "fileName": "my_document.pdf",
      "pageLayout": {
        "marginLeft": 30,
        "marginRight": 30,
        "marginTop": 22.5,
        "marginBottom": 22.5,
        "pageSize": "A4",
        "orientation": "Landscape"


Custom layout values are only supported for dynamic PDF documents. HTML layouts and static PDF documents are not supported.