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
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
Terminal vs Non-Terminal States
Terminal states indicate the transaction has reached a final outcome and will not change:completed,invalid,failed,canceled,reversed,rejected,timed_out
not_started,pending,processing,in_progress,awaiting_confirmation,broadcasted
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

