A prefill link is a short-lived, single-use route for the signer to review supplied values. It is not a permanent participant profile or proof that a waiver has already been signed. Handle its lifecycle explicitly in a booking integration.
Store only the relationship you need
When creating a link, retain the returned ID and the application reference needed to connect it to the intended task. Protect the returned URL because it carries access to the prepared signing route. Do not put it in public logs or share it as a generic event link.
Creation defaults to a 72-hour lifetime, with expiresInHours allowed from 1 to 720 under the current contract. Choose a lifetime appropriate to the planned task rather than always selecting the maximum.
Inspect the link through the documented scope
Retrieval uses prefill:write; the contract does not define a separate prefill read scope:
GET /v1/prefill-links/{id}
Authorization: Bearer YOUR_API_KEY
The response includes id, url, expiresAt and usedAt. A non-null usedAt indicates the link has been signed against and will no longer prefill. The returned URL still deserves protected handling.
Choose recovery based on the state
Use an explicit state table in your application:
| Observation | Recovery consideration |
|---|---|
| Already used | Look for the corresponding completed task before asking for another signature |
| Lifetime elapsed | Review whether the task is still needed and prepare a new link only deliberately |
| Still available | Direct the intended signer to review and complete the form |
| Lookup unavailable | Investigate the authorized record and request error without guessing |
Do not make automatic recreation an endless response to any failed link. A guest may have already completed signing, and another link can create confusion or unnecessary duplicate work.
Revalidate any new preparation
A newly created link is validated against the template’s active version. Review the allowed field values again if the template changed. Signature, initials and photo or ID captures are not prefillable, and the signer can change supplied values.
Test a used link, an expired link and a template updated between preparation attempts. Confirm that your application does not claim the old prepared values are locked or that a prefill ID alone proves completion. Use the prefill guide and retrieve reference for the complete boundary.