Submit KYB data

Submits KYB verification data for the organization. Safe to call more than once: the first call creates the provider customer and later calls update it, so a partial submission can be completed incrementally.

POST /v1/organizations/{organization_id}/kyb/submit

Submit KYB data

cURL

curl --request POST \
  --url https://api.privy.io/v1/organizations/{organization_id}/kyb/submit \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '
{
  "provider": "bridge",
  "data": {
    "business_legal_name": "<string>",
    "business_trade_name": "<string>",
    "transliterated_business_legal_name": "<string>",
    "transliterated_business_trade_name": "<string>",
    "business_description": "<string>",
    "business_type": "llc",
    "business_industry": [
      "<string>"
    ],
    "email": "[e-mail]",
    "phone": "<string>",
    "incorporation_date": "<string>",
    "is_dao": true,
    "primary_website": "<string>",
    "other_websites": [
      "<string>"
    ],
    "ownership_threshold": 15,
    "has_material_intermediary_ownership": true,
    "publicly_traded_listings": [
      {
        "market_identifier_code": "<string>",
        "stock_number": "<string>",
        "ticker": "<string>"
      }
    ],
    "associated_persons": [
      {
        "first_name": "<string>",
        "last_name": "<string>",
        "email": "[e-mail]",
        "date_of_birth": "<string>",
        "residential_address": {
          "street_line_1": "<string>",
          "city": "<string>",
          "country": "<string>",
          "street_line_2": "<string>",
          "subdivision": "<string>",
          "postal_code": "<string>"
        },
        "identifying_information": [
          {
            "type": "<string>",
            "issuing_country": "<string>",
            "number": "<string>",
            "description": "<string>",
            "expiration": "<string>",
            "image_front": "<string>",
            "image_back": "<string>"
          }
        ],
        "has_ownership": true,
        "has_control": true,
        "is_signer": true,
        "middle_name": "<string>",
        "transliterated_first_name": "<string>",
        "transliterated_middle_name": "<string>",
        "transliterated_last_name": "<string>",
        "phone": "<string>",
        "is_director": true,
        "title": "<string>",
        "ownership_percentage": 50,
        "nationalities": [
          "<string>"
        ],
        "relationship_established_at": "<string>",
        "documents": [
          {
            "purposes": [
              "proof_of_address"
            ],
            "file": "<string>",
            "description": "<string>"
          }
        ],
        "verified_database_at": "2023-11-07T05:31:56Z",
        "verified_govid_at": "2023-11-07T05:31:56Z",
        "verified_proof_of_address_at": "2023-11-07T05:31:56Z",
        "attested_ownership_structure_at": "2023-11-07T05:31:56Z"
      }
    ],
    "estimated_annual_revenue_usd": "1000000_9999999",
    "expected_monthly_payments_usd": 1,
    "source_of_funds": "sales_of_goods_and_services",
    "source_of_funds_description": "<string>",
    "account_purpose": "treasury_management",
    "account_purpose_other": "<string>",
    "acting_as_intermediary": true,
    "operates_in_prohibited_countries": true,
    "high_risk_activities": [
      "none_of_the_above"
    ],
    "high_risk_activities_explanation": "<string>",
    "conducts_money_services": true,
    "conducts_money_services_using_bridge": true,
    "conducts_money_services_description": "<string>",
    "compliance_screening_explanation": "<string>",
    "has_foreign_tax_registration": true,
    "identifying_information": [
      {
        "type": "<string>",
        "issuing_country": "<string>",
        "number": "<string>",
        "description": "<string>",
        "expiration": "<string>",
        "image_front": "<string>",
        "image_back": "<string>"
      }
    ],
    "documents": [
      {
        "purposes": [
          "business_formation"
        ],
        "file": "<string>",
        "description": "<string>"
      }
    ],
    "verified_database_at": "2023-11-07T05:31:56Z",
    "verified_govid_at": "2023-11-07T05:31:56Z",
    "verified_proof_of_address_at": "2023-11-07T05:31:56Z"
  },
  "endorsements": [
    "sepa"
  ],
  "client_agreement_id": "<string>"
}
'

200

{
  "provider": "bridge",
  "environment": "production",
  "status": "approved",
  "tos": {
    "status": "approved",
    "link": "<string>"
  },
  "endorsements": [
    {
      "name": "sepa",
      "status": "approved",
      "missing": [
        "<string>"
      ],
      "issues": [
        "<string>"
      ]
    }
  ],
  "capabilities": {
    "payin_crypto": "active",
    "payout_crypto": "active",
    "payin_fiat": "active",
    "payout_fiat": "active"
  },
  "requirements_due": [
    "<string>"
  ],
  "future_requirements_due": [
    "<string>"
  ],
  "kyb": {
    "status": "approved",
    "link": "<string>",
    "rejection_reasons": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Basic Auth header with your app ID as the username and your app secret as the password.

Headers

privy-app-id · string · required

ID of your Privy app.

Path Parameters

organization_id · string · required

The ID of the organization.

Body

application/json

Request body for headless KYB data submission.

provider · enum<string> · required

KYC/KYB provider identifier.

Available options: bridge

data · KybSubmitData · object · required

KYB verification data for headless submission. Fields are individually optional because the provider accepts partial submissions and grants endorsements once enough data has arrived; a partial submission can be completed by calling the endpoint again.

Show child attributes

environment · enum<string>

Provider environment (production or sandbox).

Available options: production, sandbox

endorsements · string[]

Endorsements to request during KYB.

Maximum array length: 1000

Endorsement identifier.

Maximum string length: 256

client_agreement_id · string

Client-side agreement ID for ToS acceptance.

Required string length: 1 - 1024

Response

200 - application/json

KYB status snapshot reflecting the submitted data.

Full KYB status for an organization with a given provider.

provider · enum<string> · required

KYC/KYB provider identifier.

Available options: bridge

environment · enum<string> · required

Provider environment (production or sandbox).

Available options: production, sandbox

status · string · required

KYC/KYB status for the user.

Example:

"approved"

tos · KyxTosStatusDetail · object · required

Terms of Service acceptance status for a KYC or KYB flow.

Show child attributes

endorsements · KyxEndorsement · object[] · required

Show child attributes

capabilities · KyxCapabilities · object · required

Capability statuses for the customer.

Show child attributes

requirements_due · string[] · required

Top-level items still needed (e.g. link a bank account).

future_requirements_due · string[] · required

Items that will be required in the future.

kyb · KyxVerificationStatusDetail · object · required

Verification status detail for a KYC or KYB check.

Show child attributes