Create a batch

POST/v1/batches

Shared files, policies and delivery defaults (including additional_security_source: csv_personal_code for the portal CSV flow). sending_mode: on_finalize (default) holds sending until send-out; rolling dispatches each delivery as added.

Body

Optional

namestring

A name for the batch, for your own reference: 1–200 characters, without control characters; leading and trailing spaces are trimmed. Default: Batch and today's date (UTC), e.g. Batch 2026-11-06.
at most 200 characters
filesarray of string

Files (fil_…) to share with every delivery in the batch, at most 20. Each must be one of your organisation's files in the same mode (test or live), or the request fails with file_reference_invalid.
sending_modestring

on_finalize (the default): the batch starts as a draft, and its deliveries wait until you send it out with POST /batches/{id}/finalize or until scheduled_at. rolling: the batch starts sending and each delivery goes out as soon as it is added; it cannot have a scheduled_at.
One of on_finalize rolling
Default "on_finalize"
defaultsobject

Delivery settings for every delivery in the batch. A delivery may set its own.
6 fields of defaults
- defaults.optionsobject
  8 fields of options
  - defaults.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
  - defaults.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
  - defaults.options.reminder_policystring · nullable
    
    The follow-up policy's ID (rpol_…): the reminders this delivery sends while it waits.
  - defaults.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.
  - defaults.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.
  - defaults.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
  - defaults.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
  - defaults.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
    
    defaults.options.notice_wording.emailstring · nullable
    
    defaults.options.notice_wording.smsstring · nullable
- defaults.additional_security_sourcestring · nullable
  
  csv_personal_code: a delivery added with a recipient.personal_code, and no recipient.conditional_authentication of its own, gets conditional_authentication: true, so only that person can open it. null or left out: no such rule.
  One of csv_personal_code
- defaults.languagestring
  
  The language (is or en) for deliveries added to the batch that do not set their own.
- defaults.messagestring
  
  The message for deliveries added to the batch that do not set their own: the plain-text note the recipient sees before signing in.
- defaults.titlestring
  
  The title for deliveries added to the batch that do not set their own: the subject the recipient sees in the notice and on their page.
- defaults.verification_levelstring
  
  The recipient.verification_level (high, substantial, medium or low) for deliveries added to the batch that do not set their own.
follow_up_policy_idstring · nullable

rpol_…, or null (the default) for no policy; never the account default. rpol_none is the same as null.
allow_policy_overrideboolean

Whether a single delivery may follow another policy than the batch's.
Default true
scheduled_atstring · date-time · nullable

Send out at this time instead of at once (on_finalize only).
send_windowobject
3 fields of send_window
- send_window.startstringrequired
  
  Local time HH:MM, inclusive.
- send_window.endstringrequired
  
  Local time HH:MM, exclusive; after start, same day.
- send_window.tzstring
  
  The time zone of start and end: always Atlantic/Reykjavik, which is UTC all year.

Returns

201 application/json. Created (status draft). See the Batch object.

Errors have one shape; see Errors for every code.