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

┌─────────┐    ┌───────────┐    ┌───────────┐
│ pending │───▶│ submitted │───▶│ completed │
└─────────┘    └───────────┘    └───────────┘
StatusDescriptionAllowed Actions
pendingDraft state. Application created but not yet submitted.Add/edit entities, upload documents, submit
submittedApplication submitted for review.View only
completedReview complete. Check application_decision for result.View only

​
Application Decisions

Once an application reaches completed status, the application_decision field contains the outcome:
DecisionDescription
approvedApplication approved. Customer can transact.
declinedApplication declined. See compliance notes for details.
withdrawnApplication was withdrawn before a decision was made.

​
Applicant-Level States (Business & Individuals)

Within an application, each entity (business or individual) has its own status: 
┌─────────┐    ┌───────────┐    ┌───────────┐
│ pending │───▶│ submitted │───▶│ completed │
└─────────┘    └───────────┘    └───────────┘
StatusDescription
pendingEntity data incomplete or not yet submitted
submittedEntity submitted for review
completedReview complete for this entity

​
Transaction Lifecycle

Transactions progress through multiple states from initiation to completion.

​
Transaction States

┌─────────────┐
│ not_started │
└──────┬──────┘
       │
       ▼
┌─────────┐    ┌────────────┐    ┌─────────────┐
│ pending │───▶│ processing │───▶│ in_progress │
└─────────┘    └────────────┘    └──────┬──────┘
                                        │
                                        ▼
                             ┌──────────────────────┐
                             │ awaiting_confirmation│
                             └──────────┬───────────┘
                                        │
                                        ▼
                             ┌─────────────┐
                             │ broadcasted │
                             └──────┬──────┘
                                    │
                                    ▼
                             ┌───────────┐
                             │ completed │
                             └───────────┘

Error States (can occur from multiple states):
┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐
│ failed  │ │ invalid  │ │ canceled │ │ rejected │ │ timed_out │
└─────────┘ └──────────┘ └──────────┘ └──────────┘ └───────────┘

​
Transaction Status Reference

StatusTerminalDescription
not_startedNoTransaction created but processing not begun
pendingNoTransaction is queued for processing
processingNoTransaction is actively being processed
in_progressNoTransaction is being processed
awaiting_confirmationNoWaiting for blockchain confirmation
broadcastedNoSubmitted to blockchain, awaiting confirmation
completedYesTransaction completed successfully
invalidYesTransaction parameters were invalid
failedYesTransaction failed during processing
canceledYesTransaction was canceled
reversedYesTransaction was reversed after completion
rejectedYesTransaction was rejected by compliance or provider
timed_outYesTransaction 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: 
┌─────────┐    ┌────────────┐    ┌───────────┐
│ pending │───▶│ processing │───▶│ completed │
└────┬────┘    └─────┬──────┘    └───────────┘
     │               │
     │               ├──────────▶┌────────┐
     │               │           │ failed │
     │               │           └────────┘
     │               │
     │               └──────────▶┌──────────┐
     │                           │ reversed │
     │                           └──────────┘
     │
     └─────────────────────────▶┌──────────┐
                                │ canceled │
                                └──────────┘
StatusTerminalDescription
pendingNoScheduled but not yet processed
processingNoCurrently being executed
completedYesSuccessfully completed
failedYesFailed during processing
canceledYesCanceled before processing
reversedYesReversed after completion

​
Handling State Changes

​
Polling for Status Updates

For non-terminal states, poll periodically to check for updates: 
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: 
// 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 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 for all error types and handling best practices.