Bulk-create documents from a template
Recipe: create and send one document per row of a CSV file, with each row's values filled in, safely and within the rate limits
In this recipe, you read a CSV file of employees and send each one a personal agreement created from the same template, with their own values filled in. The script is safe to run again after a failure: it skips rows that already have a document and uses idempotency keys so a retried request never creates a duplicate.
Before you begin
-
Python 3.9 or later, and the
requestspackage:pip install requests. -
An API key in the
SAJN_API_KEYenvironment variable. To create one, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). -
A template with a party named
Employeeand FORM subfields with the keysemployee-nameandstart-date. Store its ID inSAJN_TEMPLATE_ID. For more information, see Create documents from templates. -
A CSV file named
employees.csvwith a header row:employee_id,name,email,start_date emp-001,Alex Andersson,alex@example.com,2026-11-01 emp-002,Kai Berg,kai@example.com,2026-11-15
Build the script
Look up the keys once
Every document from the template has the same keys. To check them, create one draft in the sajn app or through the API, and list its values:
curl https://app.sajn.se/api/v1/documents/DOCUMENT_ID/field-values \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"Replace DOCUMENT_ID with the draft's ID. The response lists the values in data. Use the key of each value with filledBy set to SENDER.
Write the script
Save the following file as bulk_send.py. For each row, it finds an existing document by externalId, or creates one, fills in the values, sets the party, and sends it:
import csv
import os
import time
import requests
API = "https://app.sajn.se/api/v1"
SESSION = requests.Session()
SESSION.headers.update({
"Authorization": f"Bearer {os.environ['SAJN_API_KEY']}",
"Sajn-Version": "2026-10",
})
def call(method, path, body=None, key=None, params=None):
"""Sends one request, waiting and retrying on 429 and 5xx."""
headers = {"Idempotency-Key": key} if key else {}
for attempt in range(5):
response = SESSION.request(method, f"{API}{path}", json=body, params=params, headers=headers)
if response.status_code == 429 or response.status_code >= 500:
time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
continue
data = response.json()
if not response.ok:
message = f"{method} {path}: {data['code']} {data['message']} ({data['requestId']})"
if data["code"] == "LIMIT_EXCEEDED":
# Every later row fails the same way, so stop the run.
raise SystemExit(message)
raise RuntimeError(message)
return data
raise RuntimeError(f"{method} {path}: gave up after retries")
def send_agreement(row):
external_id = f"agreement-{row['employee_id']}"
existing = call("GET", "/documents", params={"externalId": external_id})["data"]
if existing and existing[0]["status"] != "DRAFT":
return existing[0]["id"], "already sent"
document = existing[0] if existing else call("POST", "/documents", {
"name": f"Employment agreement - {row['name']}",
"templateId": os.environ["SAJN_TEMPLATE_ID"],
"externalId": external_id,
}, key=f"{external_id}-create")
result = call("PATCH", f"/documents/{document['id']}/field-values", {
"values": [
{"key": "employee-name", "value": row["name"]},
{"key": "start-date", "value": row["start_date"]},
],
})
failed = [r for r in result["results"] if not r["success"]]
if failed:
raise RuntimeError(f"values not written: {failed}")
employee = next(p for p in document["parties"] if p["name"] in ("Employee", row["name"]))
call("PATCH", f"/documents/{document['id']}/parties/{employee['id']}", {
"name": row["name"],
"email": row["email"],
})
call("POST", f"/documents/{document['id']}/send", {}, key=f"{external_id}-send")
return document["id"], "sent"
with open("employees.csv", newline="", encoding="utf-8") as source:
for row in csv.DictReader(source):
try:
document_id, outcome = send_agreement(row)
print(f"{row['employee_id']}: {outcome} ({document_id})")
except RuntimeError as error:
print(f"{row['employee_id']}: failed: {error}")The script works as follows:
externalIdties each document to a row, so a second run finds the document instead of creating another one. TheexternalIdfilter matches the whole value.- The create request and each item in the list return the document with its
parties, so the script finds the employee's party without another request. - The idempotency keys make a retried create or send replay the first response.
- A value that isn't written doesn't fail the request. The script checks
successon each item inresults. callretries a429or5xxresponse up to five times. It waits the number of seconds inRetry-Afterwhen the header is set, and a growing delay otherwise.- On
403 LIMIT_EXCEEDED,callstops the script, because a retry can't succeed until the limit resets. Other errors fail only their row.
Run it
Run the script:
python bulk_send.pyThe output is similar to the following:
emp-001: sent (cm4k2x9p10001abcd1234efgh)
emp-002: sent (cm4k2x9p10002abcd1234efgh)Run it again, and every row reports already sent.
Handle errors
403 LIMIT_EXCEEDED: the organization reached its hourly limit for created documents, or its monthly limit for sent documents. The script stops. Run it again after the limit resets; it continues where it stopped.429 RATE_LIMITED: the script waits and retries. For the limits per plan, see Rate limits.values not written: each failed result has anerrorwith acode.NOT_FOUNDmeans the key doesn't exist on the template, andVALIDATION_FAILEDmeans the value doesn't match the field's type. Fix the CSV or the template.
For the error shape and every code, see Errors.
Related guides
Was this page helpful?
Last updated on