Use waiver submission when your integration is responsible for collecting the participant's completed answers and signature. If you only want to reduce typing before a booking, a prefill link keeps the final review and signing on the hosted form.
Use the active template structure
Read the template and match submitted values to its block IDs. Values are validated against the active version. Required answers and consent blocks must reflect the actual participant's input. A display label is not a stable substitute for a block ID.
Typed signatures are accepted only when the signature block allows typed input. Image signatures and captures have their own value requirements. Use the submission reference and image capture guide when building the request.
Make a submission identity
Choose an idempotency key for the logical signing submission and save it before sending. If the connection fails, use the same key to recover the same operation rather than creating another signature record. Do not reuse that key for a different participant or a revised submission.
Send POST /v1/waivers with the required template and values. When attaching an event, confirm it is still open. A closed event returns a conflict rather than accepting the submission into that event.
Separate signing from PDF readiness
A successful submission creates the signed record and queues its PDF. The response can report pdfStatus: pending. The signed event can also arrive before the file is ready. Your interface should show that the waiver was received while the downloadable copy is being prepared.
Retrieve the record to observe PDF readiness, then request the PDF. Do not submit the waiver again just because its file is not yet available. The PDF guide covers this state transition.
Test failure paths
Exercise missing required values, an unsupported typed signature, an outdated form and a repeated idempotency key. Confirm each produces a clear result without leaving the guest uncertain about whether they signed. Keep the response's request ID and the resulting record ID in your integration diagnostics, with sensitive answers excluded from ordinary logs.