> ## 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.

# Add associated individual to business application

> Adds a new associated individual (UBO, control person, or applicant) to a business application.
Can only be called when the application status is 'pending'. Each individual must have a unique
first and last name combination within the application.




## OpenAPI

````yaml /openapi.yaml post /applications/{application_id}/associated-individuals
openapi: 3.0.3
info:
  title: Dakota Platform API
  version: 1.0.0
  description: >-
    Combined API specification for Dakota Platform services:

    - Issuance API: Asset minting and burning operations

    - Onboarding API: Know Your Business/Customer verification

    - On/Off Ramp API: Managing on-ramp and off-ramp accounts

    - Recipients API: Managing destinations for KYB'd entities

    - Transactions API: Viewing transaction history across platform operations


    ## Authentication and API Headers


    All API endpoints require the following headers:


    - `x-idempotency-key`: Required for all POST endpoints to ensure request
    idempotency

    - `x-api-key`: Required for authentication across all endpoints


    Note: On /applications endpoints you need a token for authentication instead
    of a x-api-key

    - `x-application-token`: Required for authentication on public /applications
    endpoints (alternative to `x-api-key` where documented)



    ## Rate Limits


    Requests are rate limited per API key. Every response includes the following
    headers:


    | Header | Description |

    | --- | --- |

    | `X-RateLimit-Limit` | Maximum requests allowed in the current one-minute
    window. |

    | `X-RateLimit-Remaining` | Requests remaining in the current window. |

    | `X-RateLimit-Reset` | Absolute Unix timestamp (seconds since epoch) when
    the current rate-limit window resets. |


    When a request is throttled (`429`), responses also include `Retry-After`
    with seconds to wait before retrying.
servers:
  - url: https://api.platform.dakota.xyz
    description: Production environment
  - url: https://api.platform.sandbox.dakota.xyz
    description: Sandbox — safe for testing with simulated data
security:
  - ApiKeyAuth: []
tags:
  - name: Agentic Payments
    x-alpha: true
    description: >-
      Alpha — agent-driven payments: provision agents, draft and approve
      spending mandates, accept reviewed instructions, and manage scheduled
      payments.


      **Prerequisites:** Customer onboarded; signer groups attached for
      recognition.

      **Related:** Wallets, Signer Groups, Transactions
  - name: Mandates
    x-alpha: true
    description: >-
      Alpha — spending mandates: signed, signer-bound authorizations governing
      what may be spent, approved or cancelled by a second recognized signer (§8
      — the dual-control rule that every mandate mutation must be signed by a
      recognized signer OTHER than the bound one). Independent of agents and
      scheduled payments.


      **Prerequisites:** Signer groups attached for recognition.

      **Related:** Signer Groups, Transactions
  - name: Insights
    x-alpha: true
    description: >-
      Alpha — read-only account insight: a deterministic report over a
      customer's agentic activity (funding balances, upcoming obligations,
      failures, mandate headroom and expiry) plus an advisory chat that narrates
      it. Never moves money, never creates or changes anything.


      **Prerequisites:** Customer onboarded; insight is computed from the
      customer's scheduled payments, mandates, and wallets.

      **Related:** Agentic Payments, Mandates
  - name: Customers
    description: >-
      Manage customer entities representing businesses and organizations
      onboarded to Dakota.


      **Prerequisites:** Complete KYB via Onboarding endpoints before initiating
      money movement.

      **Related:** Onboarding, Recipients, Transactions, Accounts, Wallets
  - name: Wallets
    description: >-
      Manage wallets, balances, and wallet-to-signer-group relationships for
      custody and movement controls.


      **Prerequisites:** Customer must exist. Configure signer groups before
      policy-enforced workflows.

      **Related:** Signer Groups, Policies, Transactions, Customers
  - name: Transactions
    description: >-
      Create, cancel, and retrieve transaction records across account and wallet
      flows.


      **Prerequisites:** Accounts or destinations must be configured based on
      flow type.

      **Related:** Accounts, Recipients, Policies, Events
  - name: Recipients
    description: >-
      Manage recipient entities and destination rails used by customers for
      payouts and transfers.


      **Prerequisites:** Customer must be onboarded and active.

      **Related:** Customers, Transactions, Accounts, Onboarding
  - name: Accounts
    description: >-
      Manage account resources used for onramp, offramp, and swap operations.


      **Prerequisites:** Customer must be created and network/asset constraints
      must be known.

      **Related:** Customers, Transactions, Auto Transactions, Info
  - name: Auto Transactions
    description: >-
      Manage automated transaction configurations and execution history for
      account automation workflows.


      **Prerequisites:** Source account must exist and be configured for
      automation.

      **Related:** Accounts, Transactions, Events
  - name: Onboarding
    description: >-
      Manage KYB/KYC onboarding lifecycle, application documents, attestations,
      and verification steps.


      **Prerequisites:** Customer context and required entity/application
      metadata.

      **Related:** Customers, Exceptions, Recipients, Transactions
  - name: Policies
    description: >-
      Define and manage policy objects and rules used for transaction governance
      and risk controls.


      **Prerequisites:** Wallet and signer group resources should be configured
      for enforcement scenarios.

      **Related:** Wallets, Signer Groups, Transactions
  - name: Signer Groups
    description: >-
      Manage signer groups and signer assignments for multi-party authorization
      models.


      **Prerequisites:** Wallets should exist before linking signer groups.

      **Related:** Wallets, Policies, Transactions
  - name: Authentication
    description: >-
      Manage API authentication credentials and key lifecycle for platform
      access.


      **Prerequisites:** Client organization must be provisioned.

      **Related:** Users, Info
  - name: Users
    description: >-
      Manage client users, roles, and identity metadata for platform access
      control.


      **Prerequisites:** Auth credentials and client context must be
      established.

      **Related:** Authentication
  - name: Webhooks
    description: >-
      Manage outbound webhook targets and delivery configuration for event
      notifications.


      **Prerequisites:** Subscriber endpoint must be reachable and secured.

      **Related:** Events, Authentication
  - name: Payouts
    description: >-
      Manage where Dakota sends your accrued developer-fee payouts.


      **Prerequisites:** Auth credentials and client context must be
      established.

      **Related:** Events
  - name: Events
    description: >-
      Retrieve event records emitted by platform operations for audit and
      troubleshooting.


      **Prerequisites:** Requesting client must have access to referenced
      resources.

      **Related:** Webhooks, Transactions, Onboarding
  - name: Info
    description: >-
      Read platform capability metadata, such as supported rails, networks, and
      assets.


      **Prerequisites:** Valid authentication headers.

      **Related:** Accounts, Transactions
  - name: Sandbox
    description: >-
      Trigger sandbox-only simulation endpoints for safe end-to-end integration
      testing with synthetic data. The sandbox host
      (`https://api.platform.sandbox.dakota.xyz`) also accepts a family of
      `X-Sandbox-*` request headers on most write endpoints (`Customers`,
      `Accounts`, `Transactions`, simulate endpoints) that let integrators drive
      deterministic failure modes — pick a preset via `X-Sandbox-Scenario`, or
      compose a custom one with
      `X-Sandbox-Error-Step`/`X-Sandbox-Error-Status`/`X-Sandbox-Error-Message`.
      `X-Sandbox-Instant-Completion` collapses async flows to a single
      synchronous step, and `X-Sandbox-Skip-Auto-Approval` keeps newly created
      KYB applications in `pending` for manual-review testing. All `X-Sandbox-*`
      headers are ignored in production.


      **Prerequisites:** Sandbox environment and test customer data.

      **Related:** Customers, Accounts, Transactions, Onboarding
paths:
  /applications/{application_id}/associated-individuals:
    post:
      tags:
        - Onboarding
      summary: Add associated individual to business application
      description: >
        Adds a new associated individual (UBO, control person, or applicant) to
        a business application.

        Can only be called when the application status is 'pending'. Each
        individual must have a unique

        first and last name combination within the application.
      operationId: addAssociatedIndividual
      parameters:
        - name: application_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/KSUID'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndividualRequest'
            example:
              roles:
                - ubo
                - control_person
              name:
                first: John
                middle: Michael
                last: Doe
              title: ceo
              employment_status: employed
              ownership_percentage: 25.5
              date_of_birth: '1985-06-15'
              ssn: 123-45-6789
              nationalities:
                - US
              address:
                street1: 123 Main St
                street2: Apt 4B
                street3: Building C
                city: San Francisco
                region: California
                postal_code: '94105'
                country: US
              email_address: john.doe@acme.com
              purpose_of_account:
                - investing
                - storage_of_funds_or_digital_assets
              source_of_wealth:
                - employment
                - savings
      responses:
        '201':
          description: Individual added successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    $ref: '#/components/schemas/KSUID'
              example:
                id: 1NFHrqBHb3cTfLVkFSGmHZqdDPi
        '400':
          description: Invalid request, validation errors, or duplicate individual name
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#invalid-request
                title: >-
                  Invalid request, validation errors, or duplicate individual
                  name
                status: 400
                detail: >-
                  Invalid request, validation errors, or duplicate individual
                  name
                instance: >-
                  https://api.platform.dakota.xyz/applications/example-id/associated-individuals
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: >-
                  https://docs.dakota.xyz/api-reference/errors#authentication-error
                title: Unauthorized
                status: 401
                detail: Unauthorized
                instance: >-
                  https://api.platform.dakota.xyz/applications/example-id/associated-individuals
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '403':
          description: Application not in pending state or forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#forbidden
                title: Application not in pending state or forbidden
                status: 403
                detail: Application not in pending state or forbidden
                instance: >-
                  https://api.platform.dakota.xyz/applications/example-id/associated-individuals
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '404':
          description: Application not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#not-found
                title: Application not found
                status: 404
                detail: Application not found
                instance: >-
                  https://api.platform.dakota.xyz/applications/example-id/associated-individuals
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '409':
          description: >-
            Application already submitted or individual with same name already
            exists
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#conflict
                title: >-
                  Application already submitted or individual with same name
                  already exists
                status: 409
                detail: >-
                  Application already submitted or individual with same name
                  already exists
                instance: >-
                  https://api.platform.dakota.xyz/applications/example-id/associated-individuals
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
      security:
        - ApplicationTokenAuth: []
      externalDocs:
        description: Read full guide in docs
        url: >-
          https://docs.dakota.xyz/api-reference/onboarding/add-associated-individual-to-business-application
components:
  schemas:
    KSUID:
      type: string
      title: KSUID
      description: >-
        KSUID is a 27-character globally unique ID that combines a timestamp
        with a random component. Used for all entity identifiers in the Dakota
        platform.
      pattern: ^[0-9A-Za-z]{27}$
      minLength: 27
      maxLength: 27
      example: 1NFHrqBHb3cTfLVkFSGmHZqdDPi
    IndividualRequest:
      type: object
      description: >-
        An individual person (used for both business associated persons and
        standalone individual applications)
      required:
        - roles
        - name
        - date_of_birth
        - nationalities
        - address
        - email_address
      properties:
        roles:
          type: array
          description: >-
            Role(s) of this person (individual cannot be combined with other
            types)
          minItems: 1
          items:
            type: string
            enum:
              - ubo
              - control_person
              - applicant
              - individual
          example:
            - ubo
            - control_person
        name:
          $ref: '#/components/schemas/PersonName'
        title:
          type: string
          description: >-
            Job title (required for UBO/control person, optional for applicant,
            invalid for individual)
          enum:
            - ceo
            - coo
            - cfo
            - cto
            - cco
            - director
            - other_officer
          example: ceo
        employment_status:
          type: string
          description: Employment status (required only when roles includes 'individual')
          enum:
            - employed
            - self_employed
            - unemployed
            - student
            - retired
          example: employed
        ownership_percentage:
          type: number
          format: double
          description: >-
            Ownership percentage (required for UBO role, optional for others,
            must be > 0 and <= 100)
          minimum: 0.01
          maximum: 100
          example: 25.5
        date_of_birth:
          type: string
          format: date
          description: >-
            Date of birth (ISO 8601 format, person must be at least 18 years
            old)
          example: '1985-06-15'
        ssn:
          type: string
          description: >-
            Social Security Number (required for US persons, format:
            XXX-XX-XXXX)
          pattern: ^\d{3}-\d{2}-\d{4}$
          example: 123-45-6789
        nationalities:
          type: array
          description: ISO 3166-1 alpha-2 country codes for nationalities
          minItems: 1
          items:
            type: string
            minLength: 2
            maxLength: 2
          example:
            - US
        address:
          $ref: '#/components/schemas/Address'
        email_address:
          type: string
          format: email
          description: Email address (cannot use example or test domains)
          example: john.doe@acme.com
        purpose_of_account:
          type: array
          description: >-
            Intended purposes for the account (required when roles includes
            'individual')
          minItems: 1
          items:
            type: string
            enum:
              - investing
              - sending_and_receiving_payments
              - storage_of_funds_or_digital_assets
              - making_online_payments
              - trading_on_other_platforms
          example:
            - investing
            - storage_of_funds_or_digital_assets
        source_of_wealth:
          type: array
          description: Sources of wealth (required when roles includes 'individual')
          minItems: 1
          items:
            type: string
            enum:
              - investments
              - employment
              - court_settlement
              - lottery_winnings
              - retirement_income
              - savings
              - sale_of_assets
              - family_funds
              - gambling_winnings
              - gift
              - inheritance
              - insurance_claim
              - loan
              - redundancy_severance
              - benefits
          example:
            - employment
            - savings
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
      description: |
        Error response following RFC 9457 Problem Details.
        Public API error responses use this format.
      example:
        type: https://docs.dakota.xyz/api-reference/errors#not-found
        title: Customer Not Found
        status: 404
        detail: Customer cst_2abc123 was not found in your organization.
        instance: https://api.platform.dakota.xyz/customers/cst_2abc123
        request_id: req_7f3a8b2c
      properties:
        type:
          type: string
          format: uri
          description: |
            URI reference identifying the problem type.
            Resolves to human-readable documentation.
          example: https://docs.dakota.xyz/api-reference/errors#not-found
        title:
          type: string
          description: >-
            Short, human-readable summary of the problem type. Stable across
            occurrences.
          example: Customer Not Found
        status:
          type: integer
          description: HTTP status code for this occurrence.
          example: 404
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: Customer cst_2abc123 was not found in your organization.
        instance:
          type: string
          format: uri
          description: The request path that triggered this error.
          example: https://api.platform.dakota.xyz/customers/cst_2abc123
        request_id:
          type: string
          description: Unique request identifier. Include when contacting support.
          example: req_7f3a8b2c
        errors:
          type: array
          description: Field-level validation errors (present for validation failures).
          items:
            $ref: '#/components/schemas/ValidationError'
    PersonName:
      type: object
      description: Full name of a person
      required:
        - first
        - last
      properties:
        first:
          type: string
          description: First name
          example: John
        middle:
          type: string
          description: Middle name (optional)
          example: Michael
        last:
          type: string
          description: Last name
          example: Doe
    Address:
      type: object
      title: Address
      description: >-
        Standardized physical address format used throughout the Dakota platform
        for user and entity addresses.
      required:
        - street1
        - city
        - country
      properties:
        street1:
          type: string
          description: Primary street address line
          example: 123 Main St
        street2:
          type: string
          description: >-
            Secondary address information such as apartment, suite, or unit
            number
          example: Apt 4B
        street3:
          type: string
          description: Additional address information like building name or floor
          example: Building C
        city:
          type: string
          description: City or locality name
          example: San Francisco
        region:
          type: string
          description: Full name of state, province, or region
          example: California
        postal_code:
          type: string
          description: Postal or ZIP code
          example: '94105'
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code (two-letter country code)
          example: US
          minLength: 2
          maxLength: 2
    ValidationError:
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: Field path using dot notation for nested fields.
          example: bank_account.routing_number
        message:
          type: string
          description: Human-readable description of the field error.
          example: Routing number must be exactly 9 digits
        code:
          type: string
          description: Machine-readable error code for this field.
          example: invalid_format
  parameters:
    IdempotencyKeyHeader:
      name: x-idempotency-key
      in: header
      required: true
      description: >-
        Unique key to ensure request idempotency. If the same key is used within
        a certain time window, the original response will be returned instead of
        executing the request again.
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    ApplicationTokenAuth:
      type: apiKey
      in: header
      name: X-Application-Token
      description: >
        Application-specific token for public URL access. Generated when a
        customer is created.

        Provides access to a single application without requiring an API key.

        Token is valid for 30 days and rate-limited to 250 requests per hour.

````