# Create a delivery

`POST https://api.parasend.com/v1/deliveries`

Source: https://parasend.com/docs/api/deliveries/create

Authentication: `Authorization: Bearer <API key>` (a `ps_test_` key in test mode, `ps_live_` in live mode).
Send an `Idempotency-Key` header: a retry with the same key returns the first answer.

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.

## Body (application/json)

- `recipient` (object, required): 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`.
  - `recipient.verification_level` (string, required): 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.name` (string · nullable, optional): 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.email` (string · email · nullable, optional): 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.phone` (string · nullable, optional): E.164
  - `recipient.address` (object · nullable, optional)
    - `recipient.address.line1` (string, optional): The first address line, such as the street and number. Required.
    - `recipient.address.line2` (string · nullable, optional): A second address line, or null.
    - `recipient.address.postal_code` (string, optional): The postal code. Required.
    - `recipient.address.city` (string, optional): The town or city. Required.
    - `recipient.address.country` (string, optional): ISO 3166-1 alpha-2
    - `recipient.address.source` (string · nullable, optional): 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_authentication` (boolean, optional): 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_code` (string · nullable, optional): The recipient's Icelandic personal code (kennitala). Required when `conditional_authentication` is true at `high`.
  - `recipient.id_document_number` (string · nullable, optional): The number of the recipient's passport or ID card. Required when `conditional_authentication` is true at `substantial`.
- `files` (array of string, required): The files to send: the `fil_` IDs that Upload a file returned.
- `options` (object, optional)
  - `options.notify_channels` (array of string, optional): 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_methods` (array of string, optional): 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_policy` (string · nullable, optional): The follow-up policy's ID (`rpol_…`): the reminders this delivery sends while it waits.
  - `options.brand_profile_id` (string · nullable, optional): 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_days` (integer, optional): 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_display` (string, optional): 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_links` (boolean, optional): 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_wording` (object, optional): 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.
    - `options.notice_wording.email` (string · nullable, optional)
    - `options.notice_wording.sms` (string · nullable, optional)
- `metadata` (object, optional): Your own key–value pairs, kept with the object and returned as you sent them. Never put personal data here.
- `title` (string, optional): The subject the recipient sees in the notice and on their page.
- `message` (string, optional): A plain-text note shown before sign-in. Line breaks are kept. It is not sealed into the evidence.
- `language` (string, optional): The language of the notice and of the recipient page. One of: `is`, `en`. Default: `"is"`.

## Example: Send a PDF by e-mail

```bash
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"
    }
  }'
```

```js
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();
```

## Example: Only this kennitala may open it

```bash
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"
  }'
```

```js
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();
```

## Example: E-mail and SMS code

```bash
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
    }
  }'
```

```js
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();
```

## Response 201

Created. Includes the signed `delivery_url` for the recipient.

```json
{
  "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
  }
}
```

Errors: one shape, `{"error": {type, code, message, param, request_id}}`; every code is listed at https://parasend.com/docs/errors.