Batches

First-class container of deliveries sharing files and policies, with an aggregated monotonic funnel. Lifecycle draft → send out (/finalize) → sending → completed.

Endpoints

The Batch object

idstring

The batch's ID, starting bat_.
objectstring

Always batch.
namestring · nullable

The batch's name, for your own reference. A batch created without one is named Batch and the creation date (UTC), e.g. Batch 2026-11-06; null if it was set to null.
statusstring

draft, then scheduled (optional), sending, following_up and completed; or cancelled. Paused follow-ups are a flag, not a status.
One of draft scheduled sending following_up completed cancelled
sending_modestring

on_finalize: deliveries added to the draft wait and go out together when you send the batch out (POST /batches/{id}/finalize), or at scheduled_at. rolling: the batch is sending from the start and each delivery goes out as soon as it is added, until you close the batch with POST /batches/{id}/finalize.
One of on_finalize rolling
funnelobject

Counts that only go up: notified ≥ opened ≥ authenticated ≥ confirmed_direct, and delivered_total = confirmed_direct + rescued_by_followups.
15 fields of funnel
- funnel.totalinteger
  
  Deliveries counted.
- funnel.notifiedinteger
  
  Deliveries whose first notice has gone out.
- funnel.openedinteger
  
  Notified deliveries whose recipient opened the link, or got further.
- funnel.authenticatedinteger
  
  Notified deliveries whose recipient identified themselves, or got further (every delivered one included).
- funnel.confirmed_directinteger
  
  Deliveries whose recipient confirmed receipt after the first notice, with no follow-up.
- funnel.rescued_by_followupsinteger
  
  Deliveries whose recipient confirmed receipt only after a follow-up.
- funnel.delivered_totalinteger
  
  All delivered deliveries: confirmed_direct plus rescued_by_followups.
- funnel.expiredinteger
  
  Deliveries that expired before the recipient confirmed receipt.
- funnel.revokedinteger
  
  Deliveries that were revoked.
- funnel.auth_failedinteger
  
  Deliveries whose status is now auth_failed: the recipient's last attempt to identify themselves failed.
- funnel.bouncedinteger
  
  Deliveries that ended bounced: the recipient could not be reached.
- funnel.paper_pendinginteger
  
  Deliveries in a paper-mail step (paper_pending_approval or paper_dispatched).
- funnel.needs_addressinteger
  
  Deliveries waiting for a postal address. Currently always 0.
- funnel.bounce_ratenumber
  
  bounced as a fraction of notified, from 0 to 1, rounded to four decimals; 0 when none have been notified.
- funnel.median_time_to_confirmstring · nullable
  
  ISO 8601 duration.
createdstring · date-time

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

The follow-up policy (rpol_…) the batch's deliveries follow, unless a delivery follows its own. null: no follow-up policy (never your organisation's default policy).
allow_policy_overrideboolean

Whether a delivery in the batch may follow a different follow-up policy, named in its options.reminder_policy. When false, such a delivery is refused with policy_override_not_allowed.
follow_ups_pausedboolean

Whether the batch's follow-ups are paused (POST /batches/{id}/pause). Reminders that come due while paused wait, and go in the next send window after POST /batches/{id}/resume.
scheduled_atstring · date-time · nullable

When the batch is to be sent out, in ISO 8601 (UTC), if you gave it a send time; null otherwise. Sending out a batch with a future scheduled_at makes it scheduled until that time.
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.
defaultsobject
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.
filesarray of string

IDs of the files (fil_…) shared by every delivery in the batch. Each delivery added gets these first, then its own files.
accepting_deliveriesboolean

Whether you can add deliveries to the batch now: true for a draft, and for a rolling batch that is sending and has not been closed.
countsobject

The batch's deliveries by where they stand now. Each delivery is in exactly one of delivered, in_progress and ended, so the three add up to total.
4 fields of counts
- counts.totalinteger
- counts.deliveredinteger
- counts.in_progressinteger
- counts.endedinteger
  
  Expired, revoked, bounced or failed — not delivered.
created_byobject

Who created the batch: user_id, the member or the API key's holder (null for a key with no holder), and via, portal or api_key.
2 fields of created_by
- created_by.user_idstring · nullable
- created_by.viastring · nullable
  
  One of portal api_key
livemodeboolean

true in live mode, false in test mode.
sent_out_atstring · date-time · nullable

When the batch was sent out, in ISO 8601 (UTC); for a rolling batch, when it was closed to new deliveries. null until then; a batch cancelled first gets the time it was cancelled.
following_up_atstring · date-time · nullable

When the batch moved to following_up, in ISO 8601 (UTC): it had been sent out and every delivery in it had had its first notice. null until then.
completed_atstring · date-time · nullable

When the batch became completed, in ISO 8601 (UTC): every delivery in it had reached an end state. null until then.
cancelled_atstring · date-time · nullable

When the batch was cancelled with POST /batches/{id}/cancel, in ISO 8601 (UTC); null if it has not been.
follow_up_funnelobject

Only on GET /batches/{id}.
10 fields of follow_up_funnel
- follow_up_funnel.as_ofstring · date-time
  
  When the counts were taken, in ISO 8601 (UTC).
- follow_up_funnel.policy_idstring · nullable
  
  The follow-up policy the counts are limited to, from the policy_id query parameter (rpol_none for deliveries with no policy); null when they cover the whole batch.
- follow_up_funnel.totalinteger
  
  Deliveries counted.
- follow_up_funnel.not_yet_notifiedinteger
  
  Deliveries whose first notice has not gone out yet, such as those in a batch not yet sent out.
- follow_up_funnel.noticeobject
  
  The first notice: sent is every notified delivery and bounced those whose notice bounced; the outcome counts are the deliveries that had no reminder. email_opened counts notices whose e-mail was opened before any reminder went (a hint, not proof).
  11 fields of notice
  - follow_up_funnel.notice.sentinteger
    
    Deliveries that reached this stage: for the notice, every notified delivery; for a reminder, the deliveries that got at least this many reminders.
  - follow_up_funnel.notice.bouncedinteger
    
    Deliveries whose message at this stage bounced.
  - follow_up_funnel.notice.deliveredinteger
    
    Of the deliveries for which this was the last stage, those delivered.
  - follow_up_funnel.notice.in_progressinteger
    
    Of the deliveries for which this was the last stage, those still under way.
  - follow_up_funnel.notice.unreachableinteger
    
    Of the deliveries for which this was the last stage, those that could not be reached (bounced).
  - follow_up_funnel.notice.expiredinteger
    
    Of the deliveries for which this was the last stage, those that expired.
  - follow_up_funnel.notice.revokedinteger
    
    Of the deliveries for which this was the last stage, those revoked.
  - follow_up_funnel.notice.not_matchedinteger
    
    Of the deliveries for which this was the last stage, those that ended consignment_failed: the recipient's identification did not meet what the delivery required.
  - follow_up_funnel.notice.renotified_via_lookupinteger
  - follow_up_funnel.notice.email_openedinteger
    
    Notices whose e-mail was opened (a hint, not proof).
    at least 0
  - follow_up_funnel.notice.renotified_deliveredinteger
    
    Deliveries confirmed after a notice to a channel found by the lookup.
    at least 0
- follow_up_funnel.remindersarray of object
  
  One entry per reminder, in order (number 1, 2, 3…): sent is the deliveries that got at least that many reminders, bounced those for which it bounced, and the outcome counts the deliveries whose last reminder it was. channels counts that reminder by channel.
  10 fields of reminders
  - follow_up_funnel.reminders[].sentinteger
    
    Deliveries that reached this stage: for the notice, every notified delivery; for a reminder, the deliveries that got at least this many reminders.
  - follow_up_funnel.reminders[].bouncedinteger
    
    Deliveries whose message at this stage bounced.
  - follow_up_funnel.reminders[].deliveredinteger
    
    Of the deliveries for which this was the last stage, those delivered.
  - follow_up_funnel.reminders[].in_progressinteger
    
    Of the deliveries for which this was the last stage, those still under way.
  - follow_up_funnel.reminders[].unreachableinteger
    
    Of the deliveries for which this was the last stage, those that could not be reached (bounced).
  - follow_up_funnel.reminders[].expiredinteger
    
    Of the deliveries for which this was the last stage, those that expired.
  - follow_up_funnel.reminders[].revokedinteger
    
    Of the deliveries for which this was the last stage, those revoked.
  - follow_up_funnel.reminders[].not_matchedinteger
    
    Of the deliveries for which this was the last stage, those that ended consignment_failed: the recipient's identification did not meet what the delivery required.
  - follow_up_funnel.reminders[].numberinteger
  - follow_up_funnel.reminders[].channelsobject
    
    3 fields of channels
    
    follow_up_funnel.reminders[].channels.emailinteger
    
    follow_up_funnel.reminders[].channels.smsinteger
    
    follow_up_funnel.reminders[].channels.alternate_contactinteger
- follow_up_funnel.outcomeobject
  
  Where every counted delivery stands now, each in exactly one: delivered, in_progress, unreachable (bounced), expired, revoked, or not_matched (ended consignment_failed: the recipient's identification did not meet what the delivery required).
  6 fields of outcome
  - follow_up_funnel.outcome.deliveredinteger
  - follow_up_funnel.outcome.in_progressinteger
  - follow_up_funnel.outcome.unreachableinteger
  - follow_up_funnel.outcome.expiredinteger
  - follow_up_funnel.outcome.revokedinteger
  - follow_up_funnel.outcome.not_matchedinteger
- follow_up_funnel.confirmed_directinteger
  
  Deliveries whose recipient confirmed receipt after the first notice, with no follow-up.
- follow_up_funnel.rescued_by_followupsinteger
  
  Deliveries whose recipient confirmed receipt only after a follow-up.
- follow_up_funnel.delivered_totalinteger
  
  All delivered deliveries: confirmed_direct plus rescued_by_followups.
kpisobject

Only on GET /batches/{id}.
8 fields of kpis
- kpis.deliveredinteger
  
  Deliveries in the batch that were delivered, on the first notice or after follow-ups.
- kpis.delivered_pctnumber
  
  delivered as a percentage of the batch's deliveries, rounded to one decimal (e.g. 87.5); 0 for an empty batch.
- kpis.in_progressinteger
  
  Deliveries still under way: not yet delivered and not ended.
- kpis.median_time_to_deliverystring · nullable
  
  ISO 8601 duration.
- kpis.bounce_ratenumber
  
  The share of notified deliveries that could not be reached (bounced), as a fraction from 0 to 1 rounded to four decimals; 0 when none have been notified.
- kpis.rescued_by_followupsinteger
  
  Delivered deliveries whose recipient confirmed only after a follow-up, not on the first notice.
- kpis.spendobject
  
  An estimate of the batch's spend so far: the SMS messages sent for it (sms_messages), priced at today's prices, excluding VAT (amount, in the minor unit of currency). lookups is 0, and estimated is always true: your invoice is what counts.
  5 fields of spend
  - kpis.spend.sms_messagesinteger
  - kpis.spend.lookupsinteger
  - kpis.spend.amountinteger
  - kpis.spend.currencystring
  - kpis.spend.estimatedboolean
- kpis.vs_previousobject · nullable
  
  How this batch compares with the previous batch your organisation sent out in the same mode (cancelled batches left out): that batch's ID and the difference in delivered percentage, in percentage points. null until this batch is sent out, or when there is no earlier batch.
  2 fields of vs_previous
  - kpis.vs_previous.batch_idstring
  - kpis.vs_previous.delivered_pct_deltanumber
    
    Percentage points.