> ## Documentation Index > Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt > Use this file to discover all available pages before exploring further. # State Lifecycles > State transitions and lifecycle diagrams for Dakota API resources 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 ```mermaid theme={null} stateDiagram-v2 direction LR pending --> submitted submitted --> completed completed --> compliance_review compliance_review --> completed ``` | Status | Description | Allowed Actions | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `pending` | Draft state. Application created but not yet submitted. | Add/edit entities, upload documents, submit | | `submitted` | Application submitted for review. | View only | | `completed` | Review complete. Check `application_decision` for result. | View only (except: individuals may upload a Proof of Address via the original onboarding link to move into `compliance_review`) | | `compliance_review` | An individual customer has uploaded a Proof of Address document and is awaiting compliance review of that PoA. Reached only when the PoA-optional flow is enabled and an approved customer crosses the \$3,000 / 7-day rolling transaction threshold (or uploads a PoA via the original onboarding link). Transitions back to `completed` with an updated `application_decision` once compliance approves or rejects the PoA. | View documents; compliance approves / rejects PoA | ### Application Decisions Once an application reaches `completed` status, the `application_decision` field contains the outcome: | Decision | Description | | ----------- | ------------------------------------------------------- | | `approved` | Application approved. Customer can transact. | | `declined` | Application declined. See compliance notes for details. | | `withdrawn` | Application was withdrawn before a decision was made. | ### 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. | `poa_status` value | Meaning | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `missing` | No PoA on file. The customer has crossed the \$3,000 / 7-day rolling threshold and any inbound transactions over the limit are being held until compliance approves a submitted PoA. | | `submitted_pending_review` | PoA uploaded; awaiting compliance review. | | `approved` | PoA approved by compliance. Customer is exempt from the threshold. | | `rejected` | PoA rejected by compliance. Customer must upload a new document; the threshold continues to apply. | The `customer.kyb_status.updated` webhook event surfaces these transitions via its `reason_code` field — see [Webhook events](/documentation/webhooks#customer-events). ### Applicant-Level States (Business & Individuals) Within an application, each entity (business or individual) has its own status: ```mermaid theme={null} stateDiagram-v2 direction LR pending --> submitted submitted --> completed ``` | Status | Description | | ----------- | ------------------------------------------- | | `pending` | Entity data incomplete or not yet submitted | | `submitted` | Entity submitted for review | | `completed` | Review complete for this entity | ## Transaction Lifecycle Transactions progress through multiple states from initiation to completion. ### Transaction States ```mermaid theme={null} stateDiagram-v2 not_started --> pending pending --> processing processing --> in_progress in_progress --> awaiting_confirmation awaiting_confirmation --> broadcasted broadcasted --> completed pending --> failed pending --> canceled processing --> failed processing --> invalid processing --> rejected in_progress --> failed in_progress --> timed_out awaiting_confirmation --> failed broadcasted --> failed completed --> reversed ``` ### Transaction Status Reference | Status | Terminal | Description | | ----------------------- | -------- | -------------------------------------------------- | | `not_started` | No | Transaction created but processing not begun | | `pending` | No | Transaction is queued for processing | | `processing` | No | Transaction is actively being processed | | `in_progress` | No | Transaction is being processed | | `awaiting_confirmation` | No | Waiting for blockchain confirmation | | `broadcasted` | No | Submitted to blockchain, awaiting confirmation | | `completed` | Yes | Transaction completed successfully | | `invalid` | Yes | Transaction parameters were invalid | | `failed` | Yes | Transaction failed during processing | | `canceled` | Yes | Transaction was canceled | | `reversed` | Yes | Transaction was reversed after completion | | `rejected` | Yes | Transaction was rejected by compliance or provider | | `timed_out` | Yes | Transaction timed out | ### 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: ```mermaid theme={null} stateDiagram-v2 pending --> processing pending --> canceled processing --> completed processing --> failed completed --> reversed ``` | Status | Terminal | Description | | ------------ | -------- | ------------------------------- | | `pending` | No | Scheduled but not yet processed | | `processing` | No | Currently being executed | | `completed` | Yes | Successfully completed | | `failed` | Yes | Failed during processing | | `canceled` | Yes | Canceled before processing | | `reversed` | Yes | Reversed after completion | ## Handling State Changes ### Polling for Status Updates For non-terminal states, poll periodically to check for updates: ```javascript theme={null} async function waitForCompletion(transactionId, maxAttempts = 30) { const terminalStates = ['completed', 'failed', 'canceled', 'reversed', 'rejected', 'invalid', 'timed_out']; for (let i = 0; i < maxAttempts; i++) { const response = await fetch(`https://api.platform.dakota.xyz/auto-transactions/${transactionId}`, { headers: { 'x-api-key': API_KEY } }); const transaction = await response.json(); if (terminalStates.includes(transaction.status)) { return transaction; } // Wait before next poll (exponential backoff) await new Promise(r => setTimeout(r, Math.min(1000 * Math.pow(2, i), 30000))); } throw new Error('Transaction did not complete within expected time'); } ``` ### Using Webhooks for State Changes Instead of polling, configure webhooks to receive real-time notifications: ```javascript theme={null} // Webhook handler for transaction status changes app.post('/webhooks/dakota', (req, res) => { const event = req.body; if (event.type === 'transaction.status_changed') { const { transaction_id, old_status, new_status } = event.data; console.log(`Transaction ${transaction_id}: ${old_status} → ${new_status}`); // Handle terminal states if (['completed', 'failed', 'canceled'].includes(new_status)) { // Update your database, notify user, etc. } } res.status(200).send('OK'); }); ``` See [Webhook Integration](/documentation/webhooks) for complete webhook setup. ## 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) **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](/api-reference/errors) for all error types and handling best practices.