Deliveries

Endpoints

• POSTCreate a delivery/v1/deliveries
• GETList deliveries/v1/deliveries
• GETRetrieve a delivery/v1/deliveries/{id}
• POSTCheck a contact before sending/v1/deliveries/contact_check
• POSTSend a reminder/v1/deliveries/{id}/remind
• POSTRevoke a delivery/v1/deliveries/{id}/revoke
• DELDelete a delivery/v1/deliveries/{id}
• GETList a delivery's events/v1/deliveries/{id}/events
• GETList a delivery's e-mails and SMS/v1/deliveries/{id}/notifications
• GETList a delivery's files/v1/deliveries/{id}/files
• GETDownload a delivered file/v1/deliveries/{id}/files/{fileId}/content
• PATCHSet the recipient's postal address/v1/deliveries/{id}/address
• POSTChange a delivery's follow-up policy/v1/deliveries/{id}/policy_change
• GETGet a delivery's cost/v1/deliveries/{id}/cost
• GETGet the cost of several deliveries/v1/deliveries/costs
• GETGet delivery counts/v1/deliveries/summary

The Delivery object

• idstring

  The delivery's ID, starting dlv_.

• objectstring

  Always delivery.

• content_typestring

  What the delivery carries: files, documents.

  One of files
• statusstring

  Where a delivery is in its life. Activity such as reminders and opens is in last_activity, never a status. authenticated: the recipient has verified but not yet confirmed receipt. The end states are delivered, expired, revoked, bounced and consignment_failed.

  One of created notified opened authenticated auth_failed confirmed delivered evidence_sealed expired revoked bounced consignment_failed paper_pending_approval paper_dispatched
• last_activityobject · nullable

  The latest activity on the delivery, such as a reminder or an open; null until there is any.

• recipientobject

  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.

  11 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.verified_namestring · nullable

    The recipient's name as their eID or passport states it, once they have signed in with one; null before that, or for a confirmation without an eID or a passport check. name stays as the sender declared it (sealed into the evidence as such).

  • recipient.verified_methodstring · nullable

    How verified_name was established — the method of the sign-in it was read from (an eID, a passkey, or videoid for a passport check); null with it.

    One of audkenni smart_id sms_otp passkey videoid password link_only
  • recipient.verification_photosarray of string

    The photos kept, with the recipient's consent, from the passport or ID-card check their verified name came from: the document's photo page and the selfie. Each is at GET /deliveries/{id}/recipient_photos/{kind} (JPEG; needs evidence.read). Empty for any other method.

    One of document selfie
  • 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.

• batch_idstring · nullable

  The batch it belongs to (bat_…), or null when it is not part of a batch.

• delivery_urlstring · nullable

  Signed recipient URL (headless/embed integration).

• evidence_policystring · uri

  The evidence policy this delivery's evidence is produced under, as a URN. It is on the delivery and on every evidence record.

• certificate_languagestring

  The language of every Delivery Certificate of this delivery, the sender's and the recipient's: your organisation's certificate language when the delivery was created, never changed after. ?language= on the certificate routes may name it; the other language is 409 certificate_language_fixed.

  One of is en
• warningsarray of object

  Notices on the create response that do not stop the delivery. Show them to whoever sent it.

  2 fields of warnings

  • warnings[].codestring

    sms_otp_unavailable: SMS one-time codes that came only with the default methods were dropped, because Parasend does not send SMS to that number's country on your account. link_domain_unavailable: sent with Parasend's own links because your link domain is not working.

    One of fail_closed_delivery sms_otp_unavailable link_domain_unavailable
  • warnings[].messagestring
• sender_displayobject

  Resolved value (delivery → template → organisation default).

• operator_referencestring · nullable

  For a company sender: an opaque reference to the person who sent it, shown under the company name instead of their name. null for a personal account.

• recipient_refstring

  An opaque reference to the recipient, repeated on the evidence.

• 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
• legal_holdboolean

  Whether the delivery is under legal hold. While it is, DELETE /deliveries/{id} is refused with delete_blocked_legal_hold.

• deletion_scheduled_atstring · date-time · nullable

  Set when DELETE /deliveries/{id} has scheduled the delivery's removal; null otherwise.

• livemodeboolean

  true in live mode, false in test mode.

• createdstring · date-time

  When it was created, in ISO 8601 (UTC).

• expires_atstring · date-time · nullable

  When the delivery expires if the recipient has not confirmed receipt, in ISO 8601 (UTC): options.expires_in_days after it was created, or for a delivery in a batch, after the batch was sent out. null while its batch has not been sent out.

• metadataobject

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

• kindstring

  Unified-list discriminator. GET /deliveries returns all kinds.

  One of documents secret request
• directionstring

  inbound = a fulfillment of a document request (sender = the verified uploader).

  One of outbound inbound
  Default "outbound"
• origin_requeststring · nullable

  req_… linkage when this delivery fulfils a document request.

• follow_upobject · nullable

  Where the delivery is in its follow-up policy; null for a delivery created before follow-up policies existed.

• reminder_waitingobject · nullable

  A reminder that waits because the delivery's link domain is not working: it goes on that domain once it works again, or with Parasend's link once the domain has failed (after 72 hours). null when none waits.

  3 fields of reminder_waiting

  • reminder_waiting.sincestring · date-timerequired

    When the first waiting reminder was put off.

  • reminder_waiting.reasonstringrequired
    One of link_domain_degraded
  • reminder_waiting.link_hoststringrequired

    The delivery's link domain.

• email_waitingobject · nullable

  An e-mail that waits for your own sending address (its sender is set to hold on failure): it goes from that address once it works again, or from Parasend's at until at the latest. null when none waits.

  4 fields of email_waiting

  • email_waiting.sincestring · date-timerequired
  • email_waiting.reasonstringrequired
    One of email_sender
  • email_waiting.from_addressstring · emailrequired
  • email_waiting.untilstring · date-timerequired
• privateboolean

  Sent with a private key; written once at creation.

• titlestring · nullable

  The subject the recipient sees in the notice and on their page.

• messagestring · nullable

  The plain-text note shown before sign-in, or null.

• languagestring

  The language of the notice and of the recipient page.

  One of is en
• short_urlstring · uri · nullable

  A short link to the recipient page, the form an SMS carries.

• filesarray of object

  The delivery's files: each one's ID, its name in the delivery, and whether it is the main document.

  3 fields of files

  • files[].file_idstring
  • files[].pathstring
  • files[].primaryboolean