Skip to main content
Understanding resource state transitions is essential for building robust integrations. This guide documents the lifecycle of key resources in the Dakota API.

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 reaches completed status, the application_decision field contains the outcome:

Proof of Address State (Individuals)

For individual applications, the application-level poa_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
Non-terminal states indicate the transaction is still in progress:
  • 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:
See Webhook Integration for complete webhook setup.

State Transition Rules

Valid Transitions

Not all state transitions are valid. The API enforces these rules: Applications:
  • pendingsubmitted (via submit endpoint)
  • submittedcompleted (automatic after review)
Transactions:
  • Cannot transition from terminal states
  • canceled can only be triggered while in non-terminal state
  • reversed can only occur after completed

Error Handling

See Error Codes for all error types and handling best practices.