---
title: Lifecycle
description: How a partner creates, fills, and tracks a document set.
---

# Lifecycle

A [document set][document-sets] moves through four partner-facing steps: create
it, collect [form][forms] 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`][start-document-set] |
| 2 | Render the forms that need values. | [`GET /v1/document_sets/{id}/forms`][list-document-set-forms] |
| 3 | Submit JSON values to the returned action URL. | [Form `actions`][list-document-set-forms] |
| 4 | Poll until the document set is complete. | [`GET /v1/document_sets/{id}`][retrieve-document-set] |

## 1. Create the document set

Call [`POST /v1/document_sets`][start-document-set] to start a formation. Set
`template` to `startup_delaware-corporation` for a Delaware C-Corporation.

The response is a [`document_sets` resource][document-sets] with a Clerky app
link and the document set's initial state.

## 2. Fetch forms

Call [`GET /v1/document_sets/{id}/forms`][list-document-set-forms]. The response
includes each form's JSON Schema, [JSON Forms UI 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][list-document-set-forms] 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}`][retrieve-document-set] to refresh the
document set. Use [`state`][retrieve-document-set] 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. |

[document-sets]: ../resources/tag/document-sets
[forms]: ../resources/tag/forms
[start-document-set]: ../resources/tag/document-sets/post/v1/document_sets
[list-document-set-forms]: ../resources/tag/forms/get/v1/document_sets/id/forms
[retrieve-document-set]: ../resources/tag/document-sets/get/v1/document_sets/id
[json-forms-ui-schema]: https://jsonforms.io/docs/uischema/