# Customer Onboarding - Dakota API Implementation

## Implementation Constraints
- Maintain transactional consistency across all steps.
- Treat all saved IDs as persistent state that must be captured.
- Ensure request parameters match the configuration exactly.
- Do not create duplicate resources (recipients, destinations, accounts).
- Handle API errors gracefully with appropriate error messages.

## Before Implementation
1. Review the complete API sequence below.
2. Identify dependency relationships between steps (which IDs flow where).
3. Plan error handling strategy for each API call.
4. Then implement the complete flow.

## State Variables

These values must be captured from API responses and persisted:

| Variable | Type | Source |
|----------|------|--------|
| `CUSTOMER_ID` | string | Customer identifier from POST /customers |
| `APPLICATION_ID` | string | Application identifier for KYC/KYB |
| `APPLICATION_URL` | string | Hosted URL for customer verification |

## Authentication

All API requests require the following headers:

| Header | Description |
|--------|-------------|
| `x-api-key` | Your Dakota API key (required for all requests) |
| `x-idempotency-key` | Unique key to prevent duplicate operations (required for POST requests) |
| `Content-Type` | `application/json` |

**Environment:** Production
**Base URL:** `https://api.platform.dakota.xyz`


## Authentication

All API requests require the following headers:

| Header | Description |
|--------|-------------|
| `x-api-key` | Your Dakota API key (required for all requests) |
| `x-idempotency-key` | Unique key to prevent duplicate operations (required for POST requests) |
| `Content-Type` | `application/json` |

**Environment:** Production
**Base URL:** `https://api.platform.dakota.xyz`

## Overview
Create a new business customer in Dakota, which will trigger the KYC/KYB verification process and automatically set up their accounts.

## Configuration

| Parameter | Value |
|-----------|-------|
| Customer Type | `business` |
| Name | `Acme Corporation` |
| External ID | `usr_12345` |

## API Sequence

Execute the following API calls in order:

### Step 1: Create Customer
**`POST /customers`**
Documentation: https://docs.dakota.xyz/api-reference/customers

Request body:
```json
{
  "customer_type": "business",
  "name": "Acme Corporation",
  "external_id": "usr_12345"
}
```

This creates the customer record and returns a `customer_id` and `application_url` for identity verification.

### Step 2: Retrieve Customer Details
**`GET /customers/{customer_id}`**
Documentation: https://docs.dakota.xyz/api-reference/customers

Use the `customer_id` from Step 1 to fetch full customer details including the hosted application URL for KYC/KYB completion.

### Step 3: Check Application Status
**`GET /applications/{application_id}`**
Documentation: https://docs.dakota.xyz/api-reference/introduction

Poll this endpoint to check verification status. Status values: `pending`, `in_review`, `approved`, `rejected`.

---

## Validation Checklist

Before considering the implementation complete, verify:

- [ ] All state variables are captured and persisted correctly
- [ ] Idempotency keys are generated and included for POST requests
- [ ] Error handling exists for each API call
- [ ] API responses are validated before extracting IDs
- [ ] No hardcoded IDs - all values come from API responses

## Reference Documentation

- Customer Onboarding: https://docs.dakota.xyz/documentation/customer-onboarding
- Full API Reference: https://docs.dakota.xyz/api-reference/introduction