Bulk recipient actions

POST/api/v1/workspaces/{slug}/certificates/{id}/recipients/bulk

Issue, reissue, remind, expire, or delete many recipients in one call

Applies one action to many recipients of a certificate. Name the recipients explicitly with issue_ids, or describe them with a filter and let the API resolve it — useful when the cohort is larger than a page.

Recipients the action cannot apply to are reported as skipped rather than failing the call, so a mixed selection does the obvious thing.

Authorization

Scopecertificates:write

Authorization: Bearer vc_...

Requires certificates:write (or full access) and an active Pro seat.

Path parameters

slug*string

Workspace slug

Example: acme

id*UUID

Certificate id

Example: 550e8400-e29b-41d4-a716-446655440000

Body parameters

action*string

issue, reissue, remind, expire, or delete

Example: issue

issue_ids?UUID[]

Recipients to act on, up to 500. Omit when using filter.

Example: ["9b2c1d4e-5f67-4890-a123-456789abcdef"]

filter?object

Acts on every recipient matching search and status, the same filters List issues takes

exclude_ids?UUID[]

Recipients to leave out of a filter selection, up to 500

What each action does

Action	Applies to	Effect
`issue`	Pending recipients	Issues and emails their certificate. Costs one credit each.
`reissue`	Issued recipients on an older design	Issues a new version on the latest published design and emails them. Costs one credit each.
`remind`	Pending recipients behind an unlock form	Sends a fresh unlock link, retiring the previous one. Free.
`expire`	Issued recipients	Sets expiry to now, so the certificate stops verifying. No email, no credit.
`delete`	Any recipient	Removes the recipient. Issued certificates stop resolving publicly and credits are not returned.

issue and remind are rejected while the certificate is a draft: publishing it (PATCH /certificates/{id} with status: "active") delivers every queued recipient in one step.

Batching

issue, reissue, and remind process at most 200 recipients per call. remaining reports how many eligible recipients are left — repeat the same request until it reads 0. expire and delete are not batched.

Credits for issue are checked once for the whole batch, so a shortfall returns 402 before anything is charged.

Response schema

errors?array

failed*integer

matched*integer

remaining*integer

skipped*integer

succeeded*integer