Before processing payments, customers must complete KYB (Know Your Business) onboarding. This guide explains how to integrate Dakota Platform’s onboarding flow.

Looking for detailed onboarding guides? Check out our support articles for step-by-step walkthroughs:

Overview

The onboarding process involves:

Creating a customer record (KYB automatically initiated)
Redirecting customer to complete verification
Monitoring KYB status via API or webhooks

Step 1: Create a Customer

First, create a customer record with basic business information.

Customer Creation Fields

Field	Type	Required	Description	Example
`name`	string	✅	Legal name of the business or individual	`"Acme Corp"`
`customer_type`	string	✅	Type of customer account. Must be `"business"` or `"individual"`	`"business"`
`external_id`	string	❌	Your internal identifier for this customer	`"acme_001"`

Request Example

cURL

curl -X POST https://api.platform.dakota.xyz/customers \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "customer_type": "business"
  }'

JavaScript

const response = await fetch('https://api.platform.dakota.xyz/customers', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corp',
    customer_type: 'business'
  })
});

const customer = await response.json();
console.log('Created customer:', customer.data.id);

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/customers',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Acme Corp',
        'customer_type': 'business'
    }
)

customer = response.json()
print(f'Created customer: {customer["data"]["id"]}')

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "name": "Acme Corp",
        "customer_type": "business"
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/customers", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "name": "Acme Corp",
        "customer_type": "business"
    });
    
    let response = client
        .post("https://api.platform.dakota.xyz/customers")
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaCustomerExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "name": "Acme Corp",
              "customer_type": "business"
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/customers"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response:

{
  "id": "2Nq8G7xK9mR4Ls6DyJ1Uf3Tp",
  "kyb_links": [],
  "application_id": "2WGC9cKv9P4K8eGzqY6qJ3Xz7Qm",
  "application_url": "https://apply.dakota.com/applications/2WGC9cKv9P4K8eGzqY6qJ3Xz7Qm?token=kJ8xN3zQ9mL2pR5vY7wC1aF4dG6hK0sT8uW3nB5eM9",
  "application_expires_at": 1734567890000000000
}

Step 2: Application Process (Automatic)

An onboarding application is automatically created when you create a customer. The response includes an application_url that you can use to redirect your customer to Dakota’s hosted onboarding form.

Automatic Application Creation

When you create a customer, the system automatically:

Creates an onboarding application
Generates a secure application_url with an embedded token
Sets the initial application status to "pending"

Response Fields

The customer creation response includes:

Field	Description	Example
`id`	Unique identifier for the customer	`"2Nq8G7xK9mR4Ls6DyJ1Uf3Tp"`
`kyb_links`	Array of KYB provider links (if any)	`[]`
`application_id`	Unique identifier for the onboarding application	`"2WGC9cKv9P4K8eGzqY6qJ3Xz7Qm"`
`application_url`	Dakota-hosted onboarding URL with embedded auth token	`"https://apply.dakota.com/applications/...?token=..."`
`application_expires_at`	Unix timestamp (nanoseconds) when the application token expires (90 days from creation)	`1734567890000000000`

Using the Application URL

From the customer creation response, extract the onboarding URL:

const customer = await response.json();
const onboardingUrl = customer.application_url;

// Redirect customer to complete onboarding
window.location.href = onboardingUrl;

Re-fetching the application token. The application_url (and its embedded token) can be re-read any time with GET /customers/{customer_id} — you don’t need to store it, and nothing rotates the link while the application is still pending. The link remains valid for 90 days after creation. (An approved customer whose token has expired is a separate case — see Do not use re-engagement to resume a pending application.) The token may be used server-side (backend-to-backend); a browser handoff is not required, so you can drive the application entirely over the API with the X-Application-Token header, or redirect the customer to the hosted application_url — whichever suits your flow.

Step 3: Handle the Onboarding Flow

Direct your customer to the application_url to complete verification using Dakota’s hosted onboarding form. The customer will:

Provide business information and documentation
Add beneficial owners and control persons
Upload required documents (ID, proof of address, etc.)
Accept legal agreements (Terms of Service, Privacy Policy, etc.)
Submit the application for review
Receive approval or requests for additional information

Check readiness before submitting

Rather than parsing submission errors, read the machine-readable readiness state at any time with GET /applications/{application_id}?include=validation (or include=all). The validation object reports a top-level ready flag plus, per entity, details.missing_fields and documents.missing_documents. Submit once ready is true.

If the customer abandons the form

A customer who leaves the form part-way through resumes by reopening the original application_url. Store that URL when you create the customer, and hand the same URL back to the customer to resume. The link stays valid for 90 days from creation, and nothing in the flow consumes it early:

Closing the tab does not invalidate the link.
Submitting the application does not invalidate the link.
The customer can reopen the link as many times as they need until it expires.

Do not use re-engagement to resume a pending application

POST /customers/{customer_id}/re-engagement serves a different case: it mints a fresh token for an approved customer whose original token has expired — for example, to re-drive them through a new partner disclosure. It never changes the application’s compliance status or decision.

Customer state	How to get them back in
Pending, token still valid	Reopen the original `application_url`
Approved, token expired	`POST /customers/{customer_id}/re-engagement` returns a fresh `application_url`
Pending, token expired	Contact Dakota at support@dakota.xyz — no self-serve endpoint re-issues a pending customer’s link

Re-engagement returns 409 Conflict for a customer with no approved application, which includes every customer still in onboarding. This is deliberate: a pending customer already holds a valid link, so the endpoint refuses rather than silently rotate it.

Proof of Address for Individual Customers

For individual customer onboarding, Proof of Address (PoA) is not strictly required to complete onboarding. An individual can submit identity documents alone and reach application_status: submitted without uploading PoA. However, PoA is required for a customer to transact more than $3,000 in any rolling 7-day window. Customers who cross that threshold without an approved PoA on file are frozen — inbound transactions over the limit are held in compliance review until they provide one. Encourage customers to upload PoA at onboarding when possible; the field is presented with a note explaining the threshold rather than as a low-priority optional step.

PoA State

The application-level poa_status field on GET /applications/{id} exposes the current review state for individual customers:

`poa_status`	Meaning
`missing`	No PoA on file. Inbound transactions over the rolling-7-day threshold are paused.
`submitted_pending_review`	PoA uploaded; awaiting compliance review.
`approved`	PoA approved. Customer is exempt from the threshold gate.
`rejected`	Compliance rejected the PoA. The customer must upload a new document.
`null`	Field not applicable (business application).

Three Ways to Submit PoA After Onboarding

If a customer didn’t upload PoA at onboarding but later needs to:

Client API call. Use the standard document-upload endpoint:
POST /applications/{applicationId}/associated-individuals/{individualId}/documents
Document type can be proof_of_address, bank_statement, or utility_bill — all three are accepted as PoA-equivalent.
Customer self-serve via the original onboarding link. The link returned in application_url remains valid for 90 days after creation. When a previously-approved individual reopens it, the form locks every already-approved field and exposes only the PoA upload, so the customer can submit a PoA without re-attesting or re-entering personal data.
Compliance manual upload. A reviewer with the compliance_documents:manage permission can upload PoA on the customer’s behalf from the compliance dashboard.

Any of these paths transitions the application from completed to compliance_review (or to submitted_pending_review at the PoA level if the app hasn’t yet been decided) and emits a customer.kyb_status.updated webhook with reason_code: pending_proof_of_address. Once compliance reviews, the customer receives a follow-up event with reason_code: proof_of_address_approved or proof_of_address_rejected. See State lifecycles → Proof of Address State for the full set of transitions, and Webhooks → Customer Events for the corresponding event payloads.

Legal Agreements & Attestations

Compliance requirement: Before an application can be submitted, your customer must accept Dakota’s legal agreements. If you are building a custom onboarding flow using the API (rather than the hosted form), you are responsible for presenting these documents to your end users and collecting their consent before submitting attestations.

During onboarding, the following legal agreements must be presented and accepted:

Attestation Type	Document	Description
`e_sign`	E-Sign & Electronic Communications Notice	Consent to use electronic signatures — must be accepted first
`terms_of_service`	Terms of Service	Dakota’s terms of service
`privacy_policy`	Privacy Policy	Dakota’s privacy policy
`funds_transfer_agreement`	Funds Transfer Agreement	Agreement governing fund transfers
`lead_bank_privacy_policy`	Banking partner privacy policy	Banking partner’s privacy policy
`information_accuracy`	—	Attestation that all provided information is accurate

Submitting Attestations via API

If you are using the API to build a custom onboarding experience, you must submit attestations using the Submit Attestation endpoint. The e_sign attestation must be submitted first — all other attestations will be rejected until e-sign consent is recorded.

cURL

# Step 1: Submit e_sign first (capture timestamp)
E_SIGN_TIMESTAMP=$(date +%s)

curl -s -X POST "https://api.platform.dakota.xyz/applications/${APPLICATION_ID}/attestations" \
  -H "X-Application-Token: ${APPLICATION_TOKEN}" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{
    \"attestation_type\": \"e_sign\",
    \"timestamp\": ${E_SIGN_TIMESTAMP},
    \"applicant_id\": \"${APPLICANT_ID}\"
  }"

# Step 2: Wait to ensure a different timestamp, then submit remaining attestations
sleep 1
OTHER_TIMESTAMP=$(date +%s)

for TYPE in information_accuracy terms_of_service privacy_policy funds_transfer_agreement lead_bank_privacy_policy; do
  curl -s -X POST "https://api.platform.dakota.xyz/applications/${APPLICATION_ID}/attestations" \
    -H "X-Application-Token: ${APPLICATION_TOKEN}" \
    -H "X-Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d "{
      \"attestation_type\": \"${TYPE}\",
      \"timestamp\": ${OTHER_TIMESTAMP},
      \"applicant_id\": \"${APPLICANT_ID}\"
    }"
done

JavaScript

// Step 1: Submit e_sign first
const eSignTimestamp = Math.floor(Date.now() / 1000);

await fetch(`https://api.platform.dakota.xyz/applications/${applicationId}/attestations`, {
  method: 'POST',
  headers: {
    'X-Application-Token': applicationToken,
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attestation_type: 'e_sign',
    timestamp: eSignTimestamp,
    applicant_id: applicantId
  })
});

// Step 2: Submit remaining attestations with a later timestamp
const otherTimestamp = eSignTimestamp + 1;
const otherTypes = [
  'information_accuracy',
  'terms_of_service',
  'privacy_policy',
  'funds_transfer_agreement',
  'lead_bank_privacy_policy'
];

for (const type of otherTypes) {
  await fetch(`https://api.platform.dakota.xyz/applications/${applicationId}/attestations`, {
    method: 'POST',
    headers: {
      'X-Application-Token': applicationToken,
      'X-Idempotency-Key': crypto.randomUUID(),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      attestation_type: type,
      timestamp: otherTimestamp,
      applicant_id: applicantId
    })
  });
}

Python

import requests
import uuid
import time

# Step 1: Submit e_sign first
e_sign_timestamp = int(time.time())

requests.post(
    f'https://api.platform.dakota.xyz/applications/{application_id}/attestations',
    headers={
        'X-Application-Token': application_token,
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json',
    },
    json={
        'attestation_type': 'e_sign',
        'timestamp': e_sign_timestamp,
        'applicant_id': applicant_id,
    },
)

# Step 2: Submit remaining attestations with a later timestamp
other_timestamp = e_sign_timestamp + 1
other_types = [
    'information_accuracy',
    'terms_of_service',
    'privacy_policy',
    'funds_transfer_agreement',
    'lead_bank_privacy_policy',
]

for attestation_type in other_types:
    requests.post(
        f'https://api.platform.dakota.xyz/applications/{application_id}/attestations',
        headers={
            'X-Application-Token': application_token,
            'X-Idempotency-Key': str(uuid.uuid4()),
            'Content-Type': 'application/json',
        },
        json={
            'attestation_type': attestation_type,
            'timestamp': other_timestamp,
            'applicant_id': applicant_id,
        },
    )

The timestamp is the Unix epoch time (in seconds) when the user accepted the agreement.
The applicant_id is the individual making the attestation. For business applications, this must be a control person. For individual applications, this must be the individual themselves.
Each attestation’s timestamp must be strictly after the e_sign attestation timestamp — equal timestamps will be rejected.
All 6 attestation types are required before an application can be submitted.

Checking Missing Attestations

You can check which attestations are still needed by retrieving the application with the validation include parameter:

curl "https://api.platform.dakota.xyz/applications/{application_id}?include=attestations,validation" \
  -H "X-Application-Token: {application_token}"

The response validation.attestations field shows completed and missing attestations:

{
  "attestations": {
    "completed": [
      {
        "type": "e_sign",
        "attested_at": "2024-01-17T15:30:00Z",
        "attested_by": "John Doe"
      }
    ],
    "missing": [
      "terms_of_service",
      "privacy_policy"
    ]
  }
}

Using the hosted onboarding form? If you redirect customers to the application_url, Dakota’s hosted form handles presenting all legal agreements and collecting attestations automatically. You only need to manage attestations manually if you are building a custom onboarding UI.

Step 4: Monitor Application Status

Check onboarding status programmatically:

cURL

curl -X GET https://api.platform.dakota.xyz/customers/{customer_id} \
  -H "X-API-Key: your-api-key"

JavaScript

const response = await fetch(`https://api.platform.dakota.xyz/customers/${customerId}`, {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

const customer = await response.json();
console.log('KYB Status:', customer.kyb_status);

Python

import requests

response = requests.get(
    f'https://api.platform.dakota.xyz/customers/{customer_id}',
    headers={'X-API-Key': 'your-api-key'}
)

customer = response.json()
print(f'KYB Status: {customer["kyb_status"]}')

package main

import (
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.platform.dakota.xyz/customers/" + customerId, nil)
    
    req.Header.Add("X-API-Key", "your-api-key")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    
    let response = client
        .get(&format!("https://api.platform.dakota.xyz/customers/{}", customer_id))
        .headers(headers)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class DakotaKYBStatusExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/customers/" + customerId))
            .header("X-API-Key", "your-api-key")
            .GET()
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response:

{
  "id": "2Nq8G7xK9mR4Ls6DyJ1Uf3Tp",
  "name": "Acme Corp",
  "customer_type": "business",
  "kyb_status": "active",
  "kyb_links": [],
  "application_id": "2WGC9cKv9P4K8eGzqY6qJ3Xz7Qm",
  "created_at": 1705320600,
  "updated_at": 1705324200
}

KYB Status Values

The kyb_status field indicates the customer’s verification status:

Status	Description
`pending`	KYB verification in progress
`active`	Customer approved and can transact
`partner_review`	Under manual review
`rejected`	Verification failed
`frozen`	Account suspended

kyb_status is the authoritative gate for money movement. No recipients, destinations, accounts, or transactions can be created for a customer until kyb_status is active. The same GET /customers/{customer_id} response also carries two other status fields. Use each one for a different question:

Field	Purpose
`kyb_status`	Can this customer transact? Read this before creating accounts, recipients, destinations, or transactions.
`kyc_status`	Provider-agnostic KYC verdict for display. Returns the same values (`not_started`, `pending`, `in_review`, `approved`, `rejected`, `expired`) for both Sumsub- and Persona-verified customers. Advisory — do not use for compliance-critical decisions.
`application_status`	Where the customer sits in the onboarding lifecycle (`pending`, `submitted`, `under_review`, `request_for_information`, `admin_revision`, `approved`, `declined`, `compliance_review`). Use this to drive workflow UI.

application_status and kyb_status update independently. When compliance moves an application to request_for_information, only application_status changes. kyb_status stays on its previous value and Dakota does not fire a webhook for that transition. To surface RFI state, poll GET /applications/{application_id} and read application_status. See Application status changes that do not emit a webhook. You can also check the application status directly via the Get Application endpoint for more detailed status information.

Best Practices

User Experience

Clearly communicate the onboarding requirements
Provide progress indicators
Set expectations for processing time
Offer support contact information

Error Handling

Handle rejection gracefully
Provide clear next steps
Allow customers to restart if needed
Log all onboarding events

Compliance

Present all required legal agreements (ToS, Privacy Policy, etc.) to end users before collecting attestations
Record the exact timestamp when each agreement was accepted
Store audit trails
Monitor for suspicious activity
Keep records for compliance reporting
Regular review of rejected applications

Required Documents

Typical documents required for business verification:

Certificate of Incorporation
Bank Statements
Director/Officer Identification
Beneficial Ownership Information

Troubleshooting

Common Issues

Onboarding Stuck in “Pending”

Check if customer has accessed the onboarding URL

Repeated Rejections

Ensure document quality meets requirements
Consider manual review process

Webhook Not Received

Verify webhook endpoint is responding with 200
Check webhook signature validation
Review webhook logs in dashboard

Any issues not covered here can be addressed by contacting Dakota Platform support.

Next Steps

After successful customer onboarding:

Set up Recipients & Destinations - Configure payment targets
Create Transactions - Process payments for approved customers
Webhook Integration - Get real-time KYB status updates (see the full event list for all available events)
Testing - Test your onboarding flow

API Reference

For detailed endpoint documentation, see:

Customers API Reference - Customer creation and management
Webhooks API Reference - Real-time onboarding notifications

Playground

Documentation

Import Share Tokens

Agentic Payments

Authentication

Developer Tools

Customer Onboarding

Overview

Step 1: Create a Customer

Customer Creation Fields

Request Example

Step 2: Application Process (Automatic)

Automatic Application Creation

Response Fields

Using the Application URL

Step 3: Handle the Onboarding Flow

Check readiness before submitting

If the customer abandons the form

Do not use re-engagement to resume a pending application

Proof of Address for Individual Customers

PoA State

Three Ways to Submit PoA After Onboarding

Legal Agreements & Attestations

Submitting Attestations via API

Checking Missing Attestations

Step 4: Monitor Application Status

KYB Status Values

Best Practices

User Experience

Error Handling

Compliance

Required Documents

Troubleshooting

Common Issues

Next Steps

API Reference

​Overview

​Step 1: Create a Customer

​Customer Creation Fields

​Request Example

​Step 2: Application Process (Automatic)

​Automatic Application Creation

​Response Fields

​Using the Application URL

​Step 3: Handle the Onboarding Flow

​Check readiness before submitting

​If the customer abandons the form

​Do not use re-engagement to resume a pending application

​Proof of Address for Individual Customers

​PoA State

​Three Ways to Submit PoA After Onboarding

​Legal Agreements & Attestations

​Submitting Attestations via API

​Checking Missing Attestations

​Step 4: Monitor Application Status

​KYB Status Values

​Related status fields

​Best Practices

​User Experience

​Error Handling

​Compliance

​Required Documents

​Troubleshooting

​Common Issues

​Next Steps

​API Reference

Overview

Step 1: Create a Customer

Customer Creation Fields

Request Example

Step 2: Application Process (Automatic)

Automatic Application Creation

Response Fields

Using the Application URL

Step 3: Handle the Onboarding Flow

Check readiness before submitting

If the customer abandons the form

Do not use re-engagement to resume a pending application

Proof of Address for Individual Customers

PoA State

Three Ways to Submit PoA After Onboarding

Legal Agreements & Attestations

Submitting Attestations via API

Checking Missing Attestations

Step 4: Monitor Application Status

KYB Status Values

Related status fields

Best Practices

User Experience

Error Handling

Compliance

Required Documents

Troubleshooting

Common Issues

Next Steps

API Reference