Application Lifecycle
Applications go through a defined lifecycle from creation to decision. Understanding these states helps you build proper status handling and user feedback.Application-Level States
completed is a legacy status retained for backward compatibility; new integrations should read approved / declined. The application_decision field below is also still populated.Application Decisions
Once an application reachescompleted status, the application_decision field contains the outcome:
Proof of Address State (Individuals)
For individual applications, the application-levelpoa_status field exposes the review state of the customer’s Proof of Address document. It is null for business applications.
The
customer.kyb_status.updated webhook event surfaces these transitions via its reason_code field — see Webhook events.
Applicant-Level States (Business & Individuals)
Within an application, each entity (business or individual) has its own status:Transaction Lifecycle
Transactions progress through multiple states from initiation to completion.Transaction States
Transaction Status Reference
pending_return, returned, and pending_reversal appear on the transaction object, but they are not distinct webhook lifecycle stages. Read them from data.object.status on a *.updated event or from GET /transactions/{transaction_id} — no separate event fires for them. See Webhooks.
Terminal vs Non-Terminal States
Terminal states indicate the transaction has reached a final outcome and will not change:completed,invalid,failed,canceled,reversed,returned,rejected,timed_out
not_started,pending,processing,in_progress,awaiting_confirmation,broadcasted,pending_return,pending_reversal
Auto Transaction Lifecycle
Auto transactions have their own lifecycle:Handling State Changes
Polling for Status Updates
For non-terminal states, poll periodically to check for updates:Using Webhooks for State Changes
Instead of polling, configure webhooks to receive real-time notifications:State Transition Rules
Valid Transitions
Not all state transitions are valid. The API enforces these rules: Applications:pending→submitted(via submit endpoint)submitted→completed(automatic after review)
- Cannot transition from terminal states
canceledcan only be triggered while in non-terminal statereversedcan only occur aftercompleted

