Integrate the Registered eDelivery service in under 3 days

The integration

The Registered eDelivery service is registered with and licensed by Byggðastofnun (the Icelandic Regional Development Institute) as a postal service. It can therefore be used, among other things, to send registered mail digitally in accordance with the relevant provisions of Icelandic law. Your system uploads a PDF document and tells Justikal who should receive it. Justikal notifies the recipient, who must authenticate with an electronic ID (eID) before the document opens. Every step — sent, opened, signed — is timestamped in an event log, and you can download a formal delivery receipt certificate for every successful delivery.

The journey: 7 steps until everything is up and running

The green steps are yours; the dark steps are handled by Justikal. Only three of them involve writing code.

Before you write any code

Your first delivery, step by step

What you do next

You make one HTTP call that uploads a PDF document and tells Justikal who should receive it. Justikal then emails the recipient a secure link on your behalf. The call is a plain multipart/form-data POST — the same format as a file upload form on any website — so every HTTP client supports it out of the box.

# Replace the key and use your own email address as the recipient,
# so YOU receive the delivery and see the whole experience.
curl -X POST "https://demoapi-is.justikal.com/external/api/v1/edeliveries" \
  -H "Authorization: Bearer jkt_your_key" \
  -F "pdfFile=@/path/to/document.pdf" \
  -F "recipientName=Jón Jónsson" \
  -F "recipientCountry=IS" \
  -F "recipientPersonalCode=1234567890" \
  -F "recipientEmail=you@yourcompany.com" \
  -F "emailSubject=A test delivery from us" \
  -F "message=Please review this document and confirm receipt."

import fs from "node:fs";

const form = new FormData();
form.append("pdfFile", new Blob([fs.readFileSync("document.pdf")]), "document.pdf");
form.append("recipientName", "Jón Jónsson");
form.append("recipientCountry", "IS");
form.append("recipientPersonalCode", "1234567890");
form.append("recipientEmail", "you@yourcompany.com");
form.append("emailSubject", "A test delivery from us");
form.append("message", "Please review this document and confirm receipt.");

const res = await fetch(
  "https://demoapi-is.justikal.com/external/api/v1/edeliveries",
  { method: "POST",
    headers: { Authorization: `Bearer ${process.env.JUSTIKAL_TOKEN}` },
    body: form });
const delivery = await res.json();

import os, requests

with open("document.pdf", "rb") as f:
    res = requests.post(
        "https://demoapi-is.justikal.com/external/api/v1/edeliveries",
        headers={"Authorization": f"Bearer {os.environ['JUSTIKAL_TOKEN']}"},
        files={"pdfFile": f},
        data={
            "recipientName": "Jón Jónsson",
            "recipientCountry": "IS",
            "recipientPersonalCode": "1234567890",
            "recipientEmail": "you@yourcompany.com",
            "emailSubject": "A test delivery from us",
            "message": "Please review this document and confirm receipt.",
        })
delivery = res.json()

What comes back

{
  "id": "550e8400-e29b-41d4-a716-446655440000",   ← store this — everything else refers to it
  "status": "pending",
  "delivery_url": "https://delivery.justikal.is/550e8400-...",
  "created_at": "2026-08-11T13:54:31+00:00"
}

Done — the recipient has an email. Store the id; every other endpoint (status, event log, PDF download, report, revocation) refers to it.

What does the recipient see?

Worth understanding before you integrate — this is the experience your customers get, and exactly what you'll see when you send the first delivery to yourself.

The delivery lifecycle

A delivery has one status at a time; timestamps and the event log hold the details. This is what your integration tracks:

Choose your integration level

All three levels are fully valid in the production environment. The minimal level gets you live fastest, full integration automates everything, and advanced integration makes the experience entirely yours — your domain, your brand, your notifications.

Path A — Minimal integration

Step A1 · Send the document

Exactly the first call you made earlier. In production code the only change is reading the key from configuration and handling the response.

Step A2 · Check status (three equivalent ways)

Option 1 — no code: sign in to the dashboard and see every delivery, its status and event log. Perfectly adequate for low volume.

Option 2 — look up a single delivery:

curl "https://demoapi-is.justikal.com/external/api/v1/edeliveries/{id}" \
  -H "Authorization: Bearer jkt_your_key"

# → status, recipient and timestamps: created_at, delivered_at, signed_at, deadline_at

Option 3 — sweep everything pending (recommended for polling — one call instead of one per delivery, friendly to the 100 calls/min rate limit):

curl "https://demoapi-is.justikal.com/external/api/v1/edeliveries?status=pending&limit=50" \
  -H "Authorization: Bearer jkt_your_key"

Run this on a schedule — every 15–30 minutes is more than enough for most document workflows.

Step A3 · Download the delivery receipt certificate

# The formal delivery receipt certificate (returns 404 until delivery is complete)
curl ".../edeliveries/{id}/deliveryReport" -H "Authorization: Bearer jkt_..." -o receipt.pdf

# The document itself — use type=signed once signed_at is set
curl ".../edeliveries/{id}/pdf?type=signed" -H "Authorization: Bearer jkt_..." -o signed.pdf

Done. This is a fully valid minimal integration: one send call, one scheduled status sweep, one download when the job is finished.

Path B — Full integration

Step B1 · Set up a webhook endpoint

What you're doing: you give Justikal an HTTPS URL on your web server that gets POSTed to every time a delivery's status changes — your system reacts within seconds instead of waiting for the next poll.

// Express example — the pattern matters more than the framework
app.post("/webhooks/justikal", async (req, res) => {
  res.sendStatus(200);                       // 1. respond immediately
  const { id } = req.body;
  const delivery = await getDelivery(id);    // 2. re-fetch: the API is the source of truth
  await handleStatusChange(delivery);        // 3. idempotent: the same event twice = harmless
});

Step B2 · Send with webhook + options

curl -X POST "https://demoapi-is.justikal.com/external/api/v1/edeliveries" \
  -H "Authorization: Bearer jkt_your_key" \
  -F "pdfFile=@contract.pdf" \
  -F "recipientName=Jón Jónsson" \
  -F "recipientCountry=IS" \
  -F "recipientPersonalCode=1234567890" \
  -F "recipientEmail=jon@example.com" \
  -F "emailSubject=Your contract is ready for signature" \
  -F "postbackUrl=https://yourapp.com/webhooks/justikal" \
  -F "expiresAt=2026-09-11" \
  -F "lang=IS" \
  -F "services[]=e_delivery_signature"

Step B3 · Optional: take over the recipient experience

Step B4 · Lifecycle operations

# Revoke a delivery that hasn't been opened (only while status = pending)
curl -X POST ".../edeliveries/{id}/revoke" -H "Authorization: Bearer jkt_..."

# The full event log, event by event
curl ".../edeliveries/{id}/audit" -H "Authorization: Bearer jkt_..."

# GDPR: delete + anonymize personal data (permanent — use revoke for ordinary revocation)
curl -X DELETE ".../edeliveries/{id}" -H "Authorization: Bearer jkt_..."

Path C — Advanced integration (entirely under your own brand)

For companies that want nothing visible from Justikal in the customer journey: emails come from your address, the URL is yours, and the delivery flow happens on your own URL. Justikal runs “headless” behind the scenes.

Step C1 · Create the delivery in headless mode

What you're doing: the same creation call as always, but with the flags that shift the customer experience over to you. This is exactly the combination used in bank/collection integrations running in production:

curl -X POST "https://demoapi-is.justikal.com/external/api/v1/edeliveries" \
  -H "Authorization: Bearer jkt_your_key" \
  -F "pdfFile=@Letter_884.pdf" \
  -F "recipientName=Jón Jónsson" \
  -F "recipientCountry=IS" \
  -F "recipientPersonalCode=1234567890" \
  -F "recipientEmail=jon@example.com" \
  -F "emailSubject=placeholder" \
  -F "expiresAt=2027-01-10" \
  -F "disableNotifications=true" \    # ★ Justikal sends no email or SMS
  -F "companyBrandingUsed=true" \     # your brand on the delivery view
  -F "senderNameHidden=true" \        # company name only, no individual
  -F "hasAdditionalSecurity=true" \
  -F "postbackUrl=https://ws.yourcompany.com/deliv-endpoint" \
  -F "lang=IS"

The response contains delivery_url — the starred fields (disableNotifications and postbackUrl) are the keys the whole pattern rests on.

Step C2 · Serve the delivery behind your own URL

What you're doing: you store the delivery_url against your own document number and display it in an iframe on a page you control. The recipient's browser never shows a Justikal URL:

<!-- https://docs.yourcompany.com/doc=73883 — your page, your brand -->
<iframe
  src="https://delivery.justikal.com/is/e9842df4-1b9a-4d43-bccc-a06d00245d6b?lang=is"
  style="width:100%; height:100vh; border:0"
  allow="publickey-credentials-get">
</iframe>

Append ?lang=is (or en) to the URL to control the language of the embedded view. eID authentication, document display and delivery confirmation all happen inside the frame.

Step C3 · Send your own notification

What you're doing: since Justikal stays silent, you email or text the recipient from your own system — your sender address, your template, your deadline in the copy — with a link to your page from step C2 (not to the raw delivery_url).

Step C4 · Let webhooks drive your UI

The postbackUrl webhook (same pattern as in path B) updates your own status displays and drives your next steps — reminders from your address, case updates in your core system, automatic download of the confirmation on delivery.

What “minimal Justikal” honestly means

When something goes wrong

All errors share the same JSON format — an error code plus a readable message that names the field or rule in question:

Go-live checklist

• The integration works end to end in the test environment (send → status → delivery receipt certificate).
• Email sent to hallo@justikal.com about the contract; integration review completed; production key received.
• Base URL switched to api-is.justikal.com
• Webhook handling is idempotent; 500 retried with exponential backoff; Retry-After respected on 429.
• hasAdditionalSecurity decided per use case (default true = identity checked against the personal ID number).
• Additional services (services) in your contract confirmed with Justikal.