Lifecycle

A document set moves through four partner-facing steps: create it, collect form values, submit those values, and poll for state. Your product owns data collection and progress display; Clerky handles signing and formation work.

Workflow

Step	Your product does this	API surface
1	Create a document set from a template.	POST /v1/document_sets
2	Render the forms that need values.	GET /v1/document_sets/{id}/forms
3	Submit JSON values to the returned action URL.	Form actions
4	Poll until the document set is complete.	GET /v1/document_sets/{id}

1. Create the document set

Call POST /v1/document_sets to start a formation. Set template to startup_delaware-corporation for a Delaware C-Corporation.

The response is a document_sets resource with a Clerky app link and the document set's initial state.

2. Fetch forms

Call GET /v1/document_sets/{id}/forms. The response includes each form's JSON Schema, JSON Forms UI Schema, current values, and available actions.

Use the schemas to decide what to ask the user. Keep the form id, current values, and actions together when rendering the form.

3. Submit values

Render each form, collect JSON values, then call one of the form's returned actions using its method and url. The request body is the JSON values for that form. Treat action URLs as opaque: use them as returned, and do not hardcode action endpoints.

4. Poll for state

Call GET /v1/document_sets/{id} to refresh the document set. Use state to drive your progress UI, and continue polling until the document set reaches complete.

States

state returns one of these values. Use it to decide whether to collect more input, keep showing progress, or stop polling.

State	Recommended handling
input_needed	Collect or update form values.
signature_requests_needed	Show progress and continue polling.
awaiting_payment	Show progress and continue polling.
filing_in_progress	Show progress and continue polling.
finalizing	Show progress and continue polling.
complete	Stop polling and show completion.