{
  "info": {
    "_postman_id": "de0d1350-d76b-5182-ab36-b9406522e4b8",
    "name": "sajn Document Lifecycle",
    "description": "Create a contact and a document, add the contact as a party, send the document, get the signing URL, and get the signed PDF.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "Create a new contact",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Sajn-Version",
            "value": "{{apiVersion}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}",
            "disabled": true
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/v1/contacts",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "contacts"
          ]
        },
        "description": "Create a new contact in your organization.\n\n**Required Fields:**\n- `firstName` - Contact's first name\n\n**Optional Fields:**\n- `lastName` - Contact's last name (omit or send an empty string for single-name contacts)\n- `email` - Email address\n- `phone` - Phone number (for SMS notifications)\n- `nationalId` - National identity number, such as a Swedish personnummer, for eID verification\n- `externalId` - Your external reference ID for tracking\n- `companyId` - Associate with existing company\n- `companyRole` - Role within the company\n- `addressLine1`, `addressLine2`, `postalCode`, `city`, `state`, `country` - The contact's address",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"firstName\": \"Kai\",\n  \"lastName\": \"Lindqvist\",\n  \"email\": \"kai@example.com\",\n  \"phone\": \"+46701740605\",\n  \"externalId\": \"EMP-0142\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [],
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('Status code is 200', function () {",
              "  pm.response.to.have.status(200);",
              "});",
              "var response = {};",
              "try { response = pm.response.json(); } catch (error) {}",
              "var save = function (key, value) {",
              "  if (!value) { return; }",
              "  pm.collectionVariables.set(key, value);",
              "  if (pm.environment.name) { pm.environment.set(key, value); }",
              "};",
              "save('contactId', response.id);"
            ]
          }
        }
      ]
    },
    {
      "name": "Create a new document",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Sajn-Version",
            "value": "{{apiVersion}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}",
            "disabled": true
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/v1/documents",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "documents"
          ]
        },
        "description": "Create a new document in DRAFT status. You can optionally include parties, metadata, and responsible user during creation.\n\n**Document Types:**\n- `SIGNABLE` (default) - Standard signing document\n- `ACCEPTABLE` - Document that requires acceptance rather than signature\n- `ARCHIVE_IMPORTED` - Imported from external archive\n\n**Template Support:** Use `templateId` to create a document from a template. The template's fields and parties are copied. If you also send `parties`, they replace the template's parties, and signature and initials boxes placed on the PDF for the template's parties are removed.\n\n**CRM Link:** Use `integrationLink` to link the document to a CRM record (currently HubSpot deals). When the workspace has a field mapping configured for the integration, mapped custom fields and product-table rows are prefilled from the record, and signing status is written back to it. Explicit `customFields` in the request take precedence over prefilled values.\n\n**Responsible User:** Use `responsibleUserId` to assign a specific team member as responsible for the document. Defaults to the creating user if not specified.\n\n**Adding Parties:** Two approaches are supported:\n1. **Contact-based** (recommended): Provide `contactId` to reference existing contacts - automatically inherits all contact details\n2. **Manual**: Provide `name` and `email` to manually specify party details\n\n**Party Examples:**\n```json\n{\n  \"parties\": [\n    {\n      \"contactId\": \"contact-123\",\n      \"role\": \"SIGNER\",\n      \"signingOrder\": 1,\n      \"delivery\": [\"EMAIL\"],\n      \"signatureMethod\": \"SE_BANKID\"\n    },\n    {\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\",\n      \"role\": \"SIGNER\",\n      \"signingOrder\": 2,\n      \"delivery\": [\"SMS\"],\n      \"signatureMethod\": \"DRAWING\"\n    }\n  ]\n}\n```\n\n**Per-Party Settings:**\n- `delivery` - How the party gets the invitation: `[\"EMAIL\"]` (default), `[\"SMS\"]`, `[\"IN_APP\"]` to sign in person on your device, or `[]` to send nothing and share the signing URL yourself\n- `signatureMethod` - How the party signs: `DRAWING`, `SE_BANKID` (Swedish BankID), `CLICK_TO_SIGN`, `MANUAL`, or a national eID scheme. eID schemes are switched on market by market, so call `GET /api/v1/helpers/signature-methods` for the set your account can use\n- `signVerification` - Verification the party passes before signing: `PIN`, `SMS`, `EMAIL`, or an eID such as `SE_BANKID`. null (default) means none. Call `GET /api/v1/helpers/two-step-verifications` for the live list\n\n**Complete Workflow with Templates:**\n\n1. **Create a template** in the dashboard, and give each value you fill in a key, such as \"name\" or \"phone\".\n2. **Create, fill in, and send in one request** (this endpoint): send `templateId`, the `parties`, the values in `fieldValues`, and `send: true`. If the template has signature boxes placed for its parties, fill those parties in with `templatePartyId` so the boxes stay. To list a template's keys, create a draft and call `GET /api/v1/documents/{docId}/field-values`.\n3. **Show the document in your app**, if you embed signing: create an embed session with `POST /api/v1/embed-sessions` for the party's ID. Find the party in the response by the `ref` you gave it.\n\nEach party has its own `delivery` and `signatureMethod`. A party with `delivery: []` gets no invitation.\n\n**Example:**\n```json\nPOST /api/v1/documents\n{\n  \"name\": \"Employment Contract\",\n  \"templateId\": \"template-id-with-form-fields\",\n  \"parties\": [\n    {\n      \"templatePartyId\": \"template-party-id\",\n      \"ref\": \"employee\",\n      \"name\": \"Alex Andersson\",\n      \"email\": \"alex@example.com\",\n      \"role\": \"SIGNER\",\n      \"delivery\": [],\n      \"signatureMethod\": \"SE_BANKID\"\n    }\n  ],\n  \"fieldValues\": [\n    {\"key\": \"name\", \"value\": \"Alex Andersson\"},\n    {\"key\": \"phone\", \"value\": \"+46700000000\"}\n  ],\n  \"send\": true\n}\n```\n\nTo fill in values or add parties after creation, use `PATCH /api/v1/documents/{docId}/field-values` and `POST /api/v1/documents/{docId}/parties`, then send with `POST /api/v1/documents/{docId}/send`.\n\n**Response:** Returns the created document in the same shape as `GET /api/v1/documents/{id}`, without `fields`. Each party carries the `ref` you gave it. To get a party's signing URL, call `GET /api/v1/documents/{id}/parties/{partyId}`.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"name\": \"Anst\u00e4llningsavtal \u2013 Kai Lindqvist\",\n  \"type\": \"SIGNABLE\",\n  \"expiresAt\": \"2027-03-31T22:00:00.000Z\",\n  \"documentMeta\": {\n    \"subject\": \"Ditt anst\u00e4llningsavtal fr\u00e5n Exempelbolaget AB\",\n    \"message\": \"Hej Kai! H\u00e4r \u00e4r ditt anst\u00e4llningsavtal.\",\n    \"signingMode\": \"PARALLEL\",\n    \"language\": \"sv\"\n  },\n  \"parties\": [\n    {\n      \"name\": \"Maja Holm\",\n      \"email\": \"maja.holm@example.com\",\n      \"role\": \"SIGNER\",\n      \"company\": {\n        \"name\": \"Exempelbolaget AB\",\n        \"orgNumber\": \"5561234567\",\n        \"role\": \"HR-chef\"\n      },\n      \"country\": \"SE\",\n      \"delivery\": [\n        \"EMAIL\"\n      ],\n      \"signatureMethod\": \"DRAWING\"\n    }\n  ]\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [],
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('Status code is 200', function () {",
              "  pm.response.to.have.status(200);",
              "});",
              "var response = {};",
              "try { response = pm.response.json(); } catch (error) {}",
              "var save = function (key, value) {",
              "  if (!value) { return; }",
              "  pm.collectionVariables.set(key, value);",
              "  if (pm.environment.name) { pm.environment.set(key, value); }",
              "};",
              "save('documentId', response.id);",
              "save('partyId', response.parties && response.parties[0] && response.parties[0].id);"
            ]
          }
        }
      ]
    },
    {
      "name": "Add a party to document",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Sajn-Version",
            "value": "{{apiVersion}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}",
            "disabled": true
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/v1/documents/{{documentId}}/parties",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "documents",
            "{{documentId}}",
            "parties"
          ]
        },
        "description": "Add a party (signer/participant) to a document. The party must reference an existing contact.\n\n**Party Roles:**\n- `SIGNER` - Must sign the document\n- `ORGANIZER` - Document organizer (no signature required)\n- `REVIEWER` - Reviews document (no signature required)\n\n**Per-Party Settings:**\n- `delivery` - How the party gets the invitation: `[\"EMAIL\"]` (default), `[\"SMS\"]`, `[\"IN_APP\"]` to sign in person on your device, or `[]` to send nothing and share the signing URL yourself\n- `signatureMethod` - How the party signs: `DRAWING`, `SE_BANKID` (Swedish BankID), `CLICK_TO_SIGN`, `MANUAL`, or a national eID scheme. eID schemes are switched on market by market, so call `GET /api/v1/helpers/signature-methods` for the set your account can use\n- `signVerification` - Verification the party passes before signing: `PIN`, `SMS`, `EMAIL`, or an eID such as `SE_BANKID`. null (default) means none. Call `GET /api/v1/helpers/two-step-verifications` for the live list\n\n**Signing Order:** For SEQUENTIAL signing, specify the order (1, 2, 3...). For PARALLEL signing, order is ignored.\n\n**Response:** Returns the created party, with its `signingUrl`, in the shape of `GET /api/v1/documents/:id/parties/:partyId`. sajn logs that you read the signing URL in the document's audit trail.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"contactId\": \"{{contactId}}\",\n  \"role\": \"SIGNER\",\n  \"delivery\": [\n    \"EMAIL\"\n  ],\n  \"signatureMethod\": \"DRAWING\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [],
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('Status code is 200', function () {",
              "  pm.response.to.have.status(200);",
              "});",
              "var response = {};",
              "try { response = pm.response.json(); } catch (error) {}",
              "var save = function (key, value) {",
              "  if (!value) { return; }",
              "  pm.collectionVariables.set(key, value);",
              "  if (pm.environment.name) { pm.environment.set(key, value); }",
              "};",
              "save('partyId', response.id);"
            ]
          }
        }
      ]
    },
    {
      "name": "Send document for signing",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Sajn-Version",
            "value": "{{apiVersion}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}",
            "disabled": true
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/v1/documents/{{documentId}}/send",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "documents",
            "{{documentId}}",
            "send"
          ]
        },
        "description": "Send a document to signers for signing.\n\n**Request Body:**\n- `customMessage` (optional) - Custom message to include in the signing invitation emails/SMS. Supports newline characters (`\\n`) for line breaks. Available template variables (use `{{variableName}}` syntax): `{{firstName}}`, `{{lastName}}`, `{{fullName}}`, `{{recipientFirstName}}`, `{{recipientLastName}}`, `{{recipientFullName}}`, `{{recipientEmail}}`, `{{recipientPhone}}`, `{{recipientCompanyName}}`, `{{recipientCompanyRole}}`, `{{recipientCompanyOrgNumber}}`, `{{recipientRole}}`, `{{senderFirstName}}`, `{{senderLastName}}`, `{{senderFullName}}`, `{{senderEmail}}`, `{{senderCompanyName}}`, `{{documentName}}`, `{{documentId}}`, `{{documentValue}}`, `{{documentCreatedDate}}`, `{{expirationDate}}`, `{{signUrl}}`. Custom fields are available as `{{custom.<field-slug>}}` using the slugified field name (e.g. \"Avtalsdatum (demo)\" becomes `{{custom.avtalsdatum-demo}}`); secured fields are excluded.\n\n**Prerequisites:**\n- Document must have at least one signer added via `POST /documents/{id}/parties` or when creating the document\n- Each signer's delivery method (`EMAIL`, `SMS`, or `NONE`) and signature type (`DRAWING`, `SE_BANKID`, `CLICK_TO_SIGN`) are configured per-signer when adding them\n\n**Responses:**\n- **200** - The document is sent. Returns the document in the same shape as `GET /api/v1/documents/{id}`, without `fields`.\n- **409** with `code: \"APPROVAL_REQUIRED\"` - You lack the `SEND_WITHOUT_APPROVAL` permission, so the document needs an approval first. Request one with `POST /api/v1/approval-requests`; the document is sent when it's approved.\n- **409** with `code: \"INVALID_STATE\"` - The document isn't a draft, or its approval request is still pending.\n\n**Approved documents:** A document whose approval request is `APPROVED` but that wasn't sent automatically (`autoSend` false) stays `PENDING_APPROVAL`. The user who requested the approval sends it with this endpoint, and the invitation uses the message stored on the approval request.\n\n**What happens when you send:**\n1. Document status changes from `DRAFT` to `PENDING`\n2. sajn sends each party an invitation through the channels in its `delivery`\n3. A party with `delivery: []` gets no invitation, so share its signing URL yourself",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"customMessage\": \"Hej! H\u00e4r \u00e4r anst\u00e4llningsavtalet. L\u00e4s igenom det och signera.\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [],
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('Status code is 200', function () {",
              "  pm.response.to.have.status(200);",
              "});"
            ]
          }
        }
      ]
    },
    {
      "name": "Get a party with signing URL",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Sajn-Version",
            "value": "{{apiVersion}}"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/v1/documents/{{documentId}}/parties/{{partyId}}",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "documents",
            "{{documentId}}",
            "parties",
            "{{partyId}}"
          ]
        },
        "description": "Retrieve a specific party including their signing URL.\n\n**Security Note:** This endpoint creates an audit log entry each time a signing URL is accessed. Use this endpoint when you need the signing URL to share with the party.\n\n**Response includes:**\n- Party details (name, email, phone, company info)\n- Signing status (NOT_SIGNED, SIGNED, REJECTED)\n- Read status (NOT_OPENED, OPENED, READ)\n- Complete signing URL with token"
      },
      "response": [],
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('Status code is 200', function () {",
              "  pm.response.to.have.status(200);",
              "});",
              "var response = {};",
              "try { response = pm.response.json(); } catch (error) {}",
              "var save = function (key, value) {",
              "  if (!value) { return; }",
              "  pm.collectionVariables.set(key, value);",
              "  if (pm.environment.name) { pm.environment.set(key, value); }",
              "};",
              "save('signingUrl', response.signingUrl);"
            ]
          }
        }
      ]
    },
    {
      "name": "Get a document file",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Sajn-Version",
            "value": "{{apiVersion}}"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/v1/documents/{{documentId}}/files/{{fileType}}",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "documents",
            "{{documentId}}",
            "files",
            "{{fileType}}"
          ]
        },
        "description": "Gets one file of a document, `ORIGINAL`, `SIGNED`, or `JOURNAL`, with a pre-signed URL that works for 15 minutes.\n\nA file that isn't ready yet, such as the signed copy of a pending document, returns `409 INVALID_STATE`. To see which files are ready, call `GET /api/v1/documents/{id}/files`."
      },
      "response": [],
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('Status code is 200', function () {",
              "  pm.response.to.have.status(200);",
              "});"
            ]
          }
        }
      ]
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://app.sajn.se"
    },
    {
      "key": "apiKey",
      "value": ""
    },
    {
      "key": "apiVersion",
      "value": "2026-10"
    },
    {
      "key": "contactId",
      "value": ""
    },
    {
      "key": "documentId",
      "value": ""
    },
    {
      "key": "fileType",
      "value": "SIGNED"
    },
    {
      "key": "partyId",
      "value": ""
    },
    {
      "key": "signingUrl",
      "value": ""
    }
  ]
}
