Create a delivery

POST/v1/deliveries

Creates a delivery and sends its notice. The recipient needs at least an email or a phone; the address actually used is printed on the Delivery Certificate. Upload the files first with POST /files and pass their fil_ IDs in files. To let only one person open it, set recipient.conditional_authentication with their personal_code (eID, verification_level: high) or id_document_number (ID document check, substantial). Send an Idempotency-Key: a retry with the same key returns the first response and never sends twice.

Examples

Body

Required

recipientobjectrequired

Who receives a delivery. At least one of email and phone; phone is required at verification_level: medium, where the SMS code goes. With conditional_authentication true, only the named person can open it: personal_code is required at high (only an eID with that kennitala passes) and id_document_number at substantial (only that identity document passes). Without it, the recipient still verifies at the level you set, and their verified identity is recorded and returned to you. A mismatch is the event delivery.auth_failed, with the reason personal_code_mismatch or id_document_mismatch.
8 fields of recipient
- recipient.verification_levelstringrequired
  
  How the recipient must identify themselves before they see the documents: high, eID; substantial, a passport or ID-card check with a selfie; medium, a one-time code sent by SMS when they open the link; low, the link alone. A stronger way is always accepted.
  One of high substantial medium low
- recipient.namestring · nullable
  
  The recipient's name as you gave it, trimmed: up to 255 characters, no control characters. It is sealed into the evidence as given and never checked; null when none was given. verified_name holds the name from their eID or passport.
- recipient.emailstring · email · nullable
  
  The recipient's e-mail address, where e-mail notices and reminders go; null when not given. At least one of email and phone is required.
- recipient.phonestring · nullable
  
  E.164
- recipient.addressobject · nullable
  6 fields of address
  - recipient.address.line1string
    
    The first address line, such as the street and number. Required.
  - recipient.address.line2string · nullable
    
    A second address line, or null.
  - recipient.address.postal_codestring
    
    The postal code. Required.
  - recipient.address.citystring
    
    The town or city. Required.
  - recipient.address.countrystring
    
    ISO 3166-1 alpha-2
  - recipient.address.sourcestring · nullable
    
    Where the address came from, as you state it: thjodskra, Iceland's national registry (Þjóðskrá); customer_csv, your own records, imported from a file; manual, entered by hand. Default manual.
    One of thjodskra customer_csv manual
- recipient.conditional_authenticationboolean
  
  When true, only the person you name can open the delivery: at high their eID must carry personal_code, and at substantial their passport or ID card must carry id_document_number. Default false: the recipient still identifies themselves at the level, and you get back the identity they used.
  Default false
- recipient.personal_codestring · nullable
  
  The recipient's Icelandic personal code (kennitala). Required when conditional_authentication is true at high.
- recipient.id_document_numberstring · nullable
  
  The number of the recipient's passport or ID card. Required when conditional_authentication is true at substantial.
filesarray of stringrequired

The files to send: the fil_ IDs that Upload a file returned.

Optional

optionsobject
8 fields of options
- options.notify_channelsarray of string
  
  How the recipient is told — the invitation and every reminder go to each channel listed; each needs its contact (recipient.email, recipient.phone). Default — e-mail when there is an address, else SMS. Told on both, a failure on one channel bounces the delivery only once the other cannot arrive either.
  One of email sms
- options.auth_methodsarray of string
  
  Which ways of identifying the recipient to offer within recipient.verification_level, in your order of preference. The recipient may always use a way at least as strong as the weakest one you list. Left out: every way the level allows (an SMS code only when the recipient has a phone).
  One of audkenni smart_id sms_otp passkey videoid password link_only
- options.reminder_policystring · nullable
  
  The follow-up policy's ID (rpol_…): the reminders this delivery sends while it waits.
- options.brand_profile_idstring · nullable
  
  The brand profile's ID (bp_…). One set on the delivery wins over the batch's, and the batch's over the account's default.
- options.expires_in_daysinteger
  
  How many days the recipient has to confirm receipt before the delivery expires: a whole number from 1 to 365. Default 30. For a delivery in a batch, the days count from when the batch is sent out.
- options.sender_displaystring
  
  What the recipient and the evidence show as the sender. legal_person (your organisation's default) shows the organisation, with an opaque reference to the person who sent it; that person's name, personal code and e-mail are not shown. individual names the person who sent it as well. Your choice per delivery or template; a personal account is always individual.
  One of legal_person individual
- options.allow_parasend_linksboolean
  
  Send even though your brand profile's link domain is not working, with Parasend's own links (warning link_domain_unavailable). Without it such a delivery is refused with 409 link_domain_unavailable.
  Default false
- options.notice_wordingobject
  
  Which saved wording the first notice uses, per channel: a wording ID, null for Parasend's own, or left out for your organisation's default.
  2 fields of notice_wording
  - options.notice_wording.emailstring · nullable
  - options.notice_wording.smsstring · nullable
metadataobject

Your own key–value pairs, kept with the object and returned as you sent them. Never put personal data here.
titlestring

The subject the recipient sees in the notice and on their page.
at most 200 characters
messagestring

A plain-text note shown before sign-in. Line breaks are kept. It is not sealed into the evidence.
at most 1000 characters
languagestring

The language of the notice and of the recipient page.
One of is en
Default "is"

Returns

201 application/json. Created. Includes the signed delivery_url for the recipient. See the Delivery object.

Errors have one shape; see Errors for every code.

Code language

Request · Send a PDF by e-mail

curl -X POST "https://api.parasend.com/v1/deliveries" \
  -H "Authorization: Bearer $PARASEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Anna Björk Jónsdóttir",
      "email": "anna.bjork@example.com",
      "verification_level": "high"
    },
    "files": [
      "fil_01M6R27SZK99V6N6WG4GK15T6R"
    ],
    "title": "Final notice: invoice 2026-114",
    "language": "en",
    "metadata": {
      "case_ref": "IN-2026-114"
    }
  }'

const res = await fetch('https://api.parasend.com/v1/deliveries', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PARASEND_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    recipient: {
      name: 'Anna Björk Jónsdóttir',
      email: 'anna.bjork@example.com',
      verification_level: 'high',
    },
    files: ['fil_01M6R27SZK99V6N6WG4GK15T6R'],
    title: 'Final notice: invoice 2026-114',
    language: 'en',
    metadata: {
      case_ref: 'IN-2026-114',
    },
  }),
});
const data = await res.json();

import os, requests, uuid

res = requests.post(
    "https://api.parasend.com/v1/deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['PARASEND_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "recipient": {
            "name": "Anna Björk Jónsdóttir",
            "email": "anna.bjork@example.com",
            "verification_level": "high",
        },
        "files": ["fil_01M6R27SZK99V6N6WG4GK15T6R"],
        "title": "Final notice: invoice 2026-114",
        "language": "en",
        "metadata": {
            "case_ref": "IN-2026-114",
        },
    },
)
data = res.json()

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.parasend.com/v1/deliveries");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("PARASEND_KEY"));
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent("""
{
  "recipient": {
    "name": "Anna Björk Jónsdóttir",
    "email": "anna.bjork@example.com",
    "verification_level": "high"
  },
  "files": [
    "fil_01M6R27SZK99V6N6WG4GK15T6R"
  ],
  "title": "Final notice: invoice 2026-114",
  "language": "en",
  "metadata": {
    "case_ref": "IN-2026-114"
  }
}
""", Encoding.UTF8, "application/json");
var response = await http.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

var json = """
    {
      "recipient": {
        "name": "Anna Björk Jónsdóttir",
        "email": "anna.bjork@example.com",
        "verification_level": "high"
      },
      "files": [
        "fil_01M6R27SZK99V6N6WG4GK15T6R"
      ],
      "title": "Final notice: invoice 2026-114",
      "language": "en",
      "metadata": {
        "case_ref": "IN-2026-114"
      }
    }
    """;
var request = HttpRequest.newBuilder(URI.create("https://api.parasend.com/v1/deliveries"))
    .header("Authorization", "Bearer " + System.getenv("PARASEND_KEY"))
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(json))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.parasend.com/v1/deliveries', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('PARASEND_KEY'),
        'Idempotency-Key' => bin2hex(random_bytes(16)),
    ],
    'json' => [
        'recipient' => [
            'name' => 'Anna Björk Jónsdóttir',
            'email' => 'anna.bjork@example.com',
            'verification_level' => 'high',
        ],
        'files' => ['fil_01M6R27SZK99V6N6WG4GK15T6R'],
        'title' => 'Final notice: invoice 2026-114',
        'language' => 'en',
        'metadata' => [
            'case_ref' => 'IN-2026-114',
        ],
    ],
]);
$data = json_decode($response->getBody(), true);

curl -X POST "https://api.parasend.com/v1/deliveries" \
  -H "Authorization: Bearer $PARASEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Gervimaður Eyjaálfa",
      "email": "gervimadur@example.com",
      "verification_level": "high",
      "conditional_authentication": true,
      "personal_code": "0101304339"
    },
    "files": [
      "fil_01M6R27SZK99V6N6WG4GK15T6R"
    ],
    "title": "Court summons",
    "language": "en"
  }'

const res = await fetch('https://api.parasend.com/v1/deliveries', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PARASEND_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    recipient: {
      name: 'Gervimaður Eyjaálfa',
      email: 'gervimadur@example.com',
      verification_level: 'high',
      conditional_authentication: true,
      personal_code: '0101304339',
    },
    files: ['fil_01M6R27SZK99V6N6WG4GK15T6R'],
    title: 'Court summons',
    language: 'en',
  }),
});
const data = await res.json();

import os, requests, uuid

res = requests.post(
    "https://api.parasend.com/v1/deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['PARASEND_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "recipient": {
            "name": "Gervimaður Eyjaálfa",
            "email": "gervimadur@example.com",
            "verification_level": "high",
            "conditional_authentication": True,
            "personal_code": "0101304339",
        },
        "files": ["fil_01M6R27SZK99V6N6WG4GK15T6R"],
        "title": "Court summons",
        "language": "en",
    },
)
data = res.json()

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.parasend.com/v1/deliveries");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("PARASEND_KEY"));
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent("""
{
  "recipient": {
    "name": "Gervimaður Eyjaálfa",
    "email": "gervimadur@example.com",
    "verification_level": "high",
    "conditional_authentication": true,
    "personal_code": "0101304339"
  },
  "files": [
    "fil_01M6R27SZK99V6N6WG4GK15T6R"
  ],
  "title": "Court summons",
  "language": "en"
}
""", Encoding.UTF8, "application/json");
var response = await http.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

var json = """
    {
      "recipient": {
        "name": "Gervimaður Eyjaálfa",
        "email": "gervimadur@example.com",
        "verification_level": "high",
        "conditional_authentication": true,
        "personal_code": "0101304339"
      },
      "files": [
        "fil_01M6R27SZK99V6N6WG4GK15T6R"
      ],
      "title": "Court summons",
      "language": "en"
    }
    """;
var request = HttpRequest.newBuilder(URI.create("https://api.parasend.com/v1/deliveries"))
    .header("Authorization", "Bearer " + System.getenv("PARASEND_KEY"))
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(json))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.parasend.com/v1/deliveries', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('PARASEND_KEY'),
        'Idempotency-Key' => bin2hex(random_bytes(16)),
    ],
    'json' => [
        'recipient' => [
            'name' => 'Gervimaður Eyjaálfa',
            'email' => 'gervimadur@example.com',
            'verification_level' => 'high',
            'conditional_authentication' => true,
            'personal_code' => '0101304339',
        ],
        'files' => ['fil_01M6R27SZK99V6N6WG4GK15T6R'],
        'title' => 'Court summons',
        'language' => 'en',
    ],
]);
$data = json_decode($response->getBody(), true);

curl -X POST "https://api.parasend.com/v1/deliveries" \
  -H "Authorization: Bearer $PARASEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Anna Björk Jónsdóttir",
      "email": "anna.bjork@example.com",
      "phone": "+3540000000",
      "verification_level": "medium"
    },
    "files": [
      "fil_01M6R27SZK99V6N6WG4GK15T6R"
    ],
    "title": "Terms of your loan are changing",
    "language": "en",
    "options": {
      "notify_channels": [
        "email",
        "sms"
      ],
      "expires_in_days": 14
    }
  }'

const res = await fetch('https://api.parasend.com/v1/deliveries', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PARASEND_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    recipient: {
      name: 'Anna Björk Jónsdóttir',
      email: 'anna.bjork@example.com',
      phone: '+3540000000',
      verification_level: 'medium',
    },
    files: ['fil_01M6R27SZK99V6N6WG4GK15T6R'],
    title: 'Terms of your loan are changing',
    language: 'en',
    options: {
      notify_channels: ['email', 'sms'],
      expires_in_days: 14,
    },
  }),
});
const data = await res.json();

import os, requests, uuid

res = requests.post(
    "https://api.parasend.com/v1/deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['PARASEND_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "recipient": {
            "name": "Anna Björk Jónsdóttir",
            "email": "anna.bjork@example.com",
            "phone": "+3540000000",
            "verification_level": "medium",
        },
        "files": ["fil_01M6R27SZK99V6N6WG4GK15T6R"],
        "title": "Terms of your loan are changing",
        "language": "en",
        "options": {
            "notify_channels": ["email", "sms"],
            "expires_in_days": 14,
        },
    },
)
data = res.json()

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.parasend.com/v1/deliveries");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("PARASEND_KEY"));
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent("""
{
  "recipient": {
    "name": "Anna Björk Jónsdóttir",
    "email": "anna.bjork@example.com",
    "phone": "+3540000000",
    "verification_level": "medium"
  },
  "files": [
    "fil_01M6R27SZK99V6N6WG4GK15T6R"
  ],
  "title": "Terms of your loan are changing",
  "language": "en",
  "options": {
    "notify_channels": [
      "email",
      "sms"
    ],
    "expires_in_days": 14
  }
}
""", Encoding.UTF8, "application/json");
var response = await http.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

var json = """
    {
      "recipient": {
        "name": "Anna Björk Jónsdóttir",
        "email": "anna.bjork@example.com",
        "phone": "+3540000000",
        "verification_level": "medium"
      },
      "files": [
        "fil_01M6R27SZK99V6N6WG4GK15T6R"
      ],
      "title": "Terms of your loan are changing",
      "language": "en",
      "options": {
        "notify_channels": [
          "email",
          "sms"
        ],
        "expires_in_days": 14
      }
    }
    """;
var request = HttpRequest.newBuilder(URI.create("https://api.parasend.com/v1/deliveries"))
    .header("Authorization", "Bearer " + System.getenv("PARASEND_KEY"))
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(json))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.parasend.com/v1/deliveries', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('PARASEND_KEY'),
        'Idempotency-Key' => bin2hex(random_bytes(16)),
    ],
    'json' => [
        'recipient' => [
            'name' => 'Anna Björk Jónsdóttir',
            'email' => 'anna.bjork@example.com',
            'phone' => '+3540000000',
            'verification_level' => 'medium',
        ],
        'files' => ['fil_01M6R27SZK99V6N6WG4GK15T6R'],
        'title' => 'Terms of your loan are changing',
        'language' => 'en',
        'options' => [
            'notify_channels' => ['email', 'sms'],
            'expires_in_days' => 14,
        ],
    ],
]);
$data = json_decode($response->getBody(), true);

Response · 201

{
  "id": "dlv_01M6R27T05512SCV3852TPM2XY",
  "object": "delivery",
  "kind": "documents",
  "direction": "outbound",
  "content_type": "files",
  "status": "created",
  "last_activity": null,
  "title": "Final notice: invoice 2026-114",
  "message": null,
  "language": "en",
  "certificate_language": "is",
  "recipient": {
    "name": "Anna Björk Jónsdóttir",
    "verified_name": null,
    "verified_method": null,
    "verification_photos": [],
    "email": "anna.bjork@example.com",
    "phone": null,
    "address": null,
    "verification_level": "high",
    "conditional_authentication": false,
    "personal_code": null,
    "id_document_number": null
  },
  "files": [
    {
      "file_id": "fil_01M6R27SZK99V6N6WG4GK15T6R",
      "path": "test-notice.pdf",
      "primary": true
    }
  ],
  "batch_id": null,
  "delivery_url": "https://parasend.com/d/dlv_01M6R27T05512SCV3852TPM2XY.5HUZcfzvQDAcjpVG.pUZ-uQ3Zeu8y3UB-1O0rXywI30QlFNxQ",
  "short_url": "https://parasend.com/d/RM1RyXl0",
  "evidence_policy": "urn:parasend:policy:evidence:standard:1",
  "sender_display": "legal_person",
  "operator_reference": "OP-7K3Q-M2",
  "recipient_ref": "rcp_01M6R27T05ZNSRNMAW2CA8MTF6",
  "private": false,
  "options": {
    "auth_methods": [
      "audkenni",
      "smart_id",
      "passkey"
    ],
    "reminder_policy": null,
    "brand_profile_id": null,
    "expires_in_days": 30,
    "sender_display": "legal_person",
    "notify_channels": [
      "email"
    ]
  },
  "legal_hold": false,
  "deletion_scheduled_at": null,
  "livemode": false,
  "created": "2026-11-06T09:15:05.604Z",
  "expires_at": "2026-12-06T09:15:05.603Z",
  "metadata": {
    "case_ref": "IN-2026-114"
  },
  "origin_request": null,
  "reminder_waiting": null,
  "email_waiting": null,
  "follow_up": {
    "policy_id": null,
    "policy_name": null,
    "policy_source": "none",
    "state": "done",
    "reminders_sent": 0,
    "last_step": null,
    "next_step": null,
    "paused": false
  }
}