> ## Documentation Index > Fetch the complete documentation index at: https://docs.capa.fi/llms.txt > Use this file to discover all available pages before exploring further. # Submit Business Profile Submits a business's KYB (Know Your Business) data for verification. The endpoint accepts the submission and returns immediately with `202 Accepted` — the underlying AiPrise call chain (session creation, business profile creation, questionnaire, document uploads, related-person verification, and running the verification) is driven asynchronously in the background. Poll [`GET /details`](/reference/kybpartnercontrollerv2_getuserkybdetails) to track progress and retrieve the final verification result. *** ## Important Notes * This endpoint always returns `202 Accepted` with `submissionStage: "DRAFT"` and no `externalResourceId` — the AiPrise call chain hasn't started yet at response time. * Only one KYB submission can be in progress per user at a time. Submitting again while a prior submission is `IN_PROGRESS` returns the existing verification instead of creating a new one. * An optional `Idempotency-Key` header (16–128 printable ASCII characters) protects against duplicate submissions from client-side retries — a repeated request with the same key and body replays the original response instead of processing twice. * `country` accepts `MX`, `US`, `DO`, or any SEPA-region country code for EUR-market businesses. * Several fields are conditionally required based on other answers (e.g. `isUsMsb` fields only apply when `country` is `US`; `mx*` fields only apply when `country` is `MX`) — see each field's description in the schema. * Every `relatedPersons` entry represents a UBO, director, authorized representative, controlling person, or legal representative — at least one is required. `taxRegistrationDocument`, `beneficialOwnerDeclarationDocument`, and `accountStatementDocument` are optional per person and only relevant in specific markets/products (see field descriptions). * All document fields expect base64-encoded file content (`fileBase64`) alongside a `fileName`. *** ## Use Cases * **Business onboarding**: Collect and submit a business's full KYB questionnaire and supporting documents in a single call without blocking on AiPrise's processing time. * **Status tracking**: Combine with `GET /details` to build a progress UI for partners while the verification runs in the background. *** ## Error Codes ### Common Errors | HTTP Status | Code | Message | | ----------- | ---------------------- | ---------------------------------- | | 401 | `UNAUTHORIZED` | "API Key is missing" | | 401 | `UNAUTHORIZED` | "Invalid API Key format" | | 401 | `UNAUTHORIZED` | "Invalid API Key" | | 403 | `INVALID_PARTNER_FLOW` | "The partner has an invalid flow." | ### User Ownership Errors | HTTP Status | Code | Message | | ----------- | -------------- | ---------------------------------------------------- | | 401 | `UNAUTHORIZED` | "Partner information is required for this operation" | | 401 | `UNAUTHORIZED` | "User is not associated with the partner" | ### Idempotency Errors | HTTP Status | Code | Message | | ----------- | ------------- | ----------------------------------------------------------------- | | 400 | `BAD_REQUEST` | "Idempotency-Key "..." must be 16–128 printable ASCII characters" | | 409 | `CONFLICT` | "Idempotency-Key was already used with a different request body" | ### Endpoint-Specific Errors | HTTP Status | Code | Message | | ----------- | ----------------------- | ------------------------------------------------------- | | 400 | `BAD_REQUEST` | Request body validation failure (missing/invalid field) | | 422 | `UNPROCESSABLE_ENTITY` | "KYB submission requires a BUSINESS user" | | 500 | `INTERNAL_SERVER_ERROR` | "Internal server error" | ## OpenAPI ````yaml reference/openapi/KYBPartnerControllerV2_submitBusinessProfile.json POST /api/partner/v2/kyb openapi: 3.0.0 info: title: Capa Partner API - V2 description: >- Partner API for integrating cryptocurrency on-ramp and off-ramp services using Capa's infrastructure. Enable your users to seamlessly convert between fiat and crypto. version: v2 contact: {} servers: - url: https://api.sandbox.capa.fi - url: https://production-api.capa.fi security: [] paths: /api/partner/v2/kyb: post: tags: - kyb operationId: KYBPartnerControllerV2_submitBusinessProfile parameters: - name: Idempotency-Key in: header required: false description: >- Optional client-generated key (16-128 printable ASCII characters). If provided, a retried request with the same key and body replays the original response instead of creating a second submission. schema: type: string example: b7e1c2b0-2f3a-4a5b-9c0e-1a2b3c4d5e6f requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitKYBBusinessProfileBody' responses: '202': description: >- Business profile accepted for asynchronous processing — the AiPrise call chain runs in the background. Poll GET /details for progress. content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/SubmitKYBBusinessProfileHttpResponse' example: success: true data: verificationId: f47ac10b-58cc-4372-a567-0e02b2c3d479 status: IN_PROGRESS submissionStage: DRAFT country: MX createdAt: '2026-08-26T00:00:00.000Z' updatedAt: '2026-08-26T00:00:00.000Z' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: VALIDATION_ERROR: value: success: false code: BAD_REQUEST message: >- "businessModelDescription" length must be at least 100 characters long INVALID_IDEMPOTENCY_KEY: value: success: false code: BAD_REQUEST message: >- Idempotency-Key "short" must be 16–128 printable ASCII characters '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: MISSING_API_KEY: value: success: false code: UNAUTHORIZED message: API Key is missing INVALID_API_KEY: value: success: false code: UNAUTHORIZED message: Invalid API Key USER_NOT_ASSOCIATED: value: success: false code: UNAUTHORIZED message: User is not associated with the partner '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false code: CONFLICT message: Idempotency-Key was already used with a different request body '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false code: UNPROCESSABLE_ENTITY message: KYB submission requires a BUSINESS user '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false code: INTERNAL_SERVER_ERROR message: Internal server error security: - PartnerApiKey: [] components: schemas: SubmitKYBBusinessProfileBody: type: object required: - userId - country - businessName - incorporationDate - incorporationCountry - businessAddress - termsAndConditionsAcceptance - industry - legalEntityType - businessModelDescription - sourceOfFunds - accountPurpose - licenses - counterpartyCountries - expectedFiatMonthlyVolume - expectedCryptoMonthlyVolume - primaryTargetMarket - expectedCryptoMonthlyOperationCount - expectedFiatMonthlyOperationCount - operatingCountries - highRiskIndustryExposure - asiaExposure - capaProducts - regulatedCountries - businessRegistrationDocument - addressProofDocument - bankStatementDocument - directorsRegistry - articlesOfIncorporation - shareholdersRegistry - taxRegistrationCertificate - relatedPersons properties: userId: type: string format: uuid country: type: string enum: - MX - US - DO description: >- Also accepts any SEPA-region ISO alpha-2 code for EUR-market businesses. businessName: type: string dbaName: type: string taxId: type: string website: type: string format: uri incorporationDate: type: string format: date incorporationCountry: type: string description: ISO 3166-1 alpha-2. registrationEntityId: type: string stateCode: type: string businessAddress: $ref: '#/components/schemas/PhysicalAddress' registeredAddress: allOf: - $ref: '#/components/schemas/PhysicalAddress' description: Only if different from businessAddress. contactPhone: type: string contactEmail: type: string format: email termsAndConditionsAcceptance: type: object required: - dateTime properties: dateTime: type: string format: date-time industry: type: string enum: - Financial services - Crypto / digital assets - Technology - Real estate - Construction - Energy - Entertainment - Health - Professional services - Trade / commerce - Gambling / gaming - Non-profit - Government - Other industryOtherDescription: type: string description: Required if industry is "Other". financialServicesSubtype: type: string description: Required if industry is "Financial services". cryptoSubtype: type: string enum: - Protocol - Exchange - Investment - Lending - Market maker - SaaS - Mining - Custody - Virtual asset service provider (VASP) - Other description: Required if industry is "Crypto / digital assets". legalEntityType: type: string enum: - Limited Liability Company (LLC) - Corporation - Partnership - Sole proprietorship - Non-profit organization - Other legalEntityTypeOtherDescription: type: string description: Required if legalEntityType is "Other". businessModelDescription: type: string minLength: 100 sourceOfFunds: type: array minItems: 1 items: type: string enum: - Business revenue - Employment income - Investment income - Loans / financing - Donations - Third-party funds - Other sourceOfFundsOtherDescription: type: string description: Required if sourceOfFunds includes "Other". accountPurpose: type: array minItems: 1 items: type: string enum: - Business operations - Payroll - Cross-border payments - Domestic payments - Personal remittances - Investment - Treasury management - Third-party money transmission - Charitable / donations - Personal expenses - Other accountPurposeOtherDescription: type: string description: Required if accountPurpose includes "Other". licenses: type: array minItems: 1 items: type: string enum: - Money Services Business (MSB) - Money transmitter license - Virtual Asset Service Provider (VASP) - Crypto-Asset Service Provider (CASP / MiCA) - Electronic Money Institution (EMI) - Payment institution (PSD2) - Banking license - Broker-dealer license - Trust company - None / not applicable - Other licensesOtherDescription: type: string description: Required if licenses includes "Other". counterpartyCountries: type: array minItems: 1 items: type: string expectedFiatMonthlyVolume: type: string enum: - Less than $5,000 USD - $5,000 – $50,000 USD - $50,000 – $500,000 USD - $500,000 – $5,000,000 USD - More than $5,000,000 USD expectedCryptoMonthlyVolume: type: string enum: - No crypto activity - Less than $5,000 USD - $5,000 – $50,000 USD - $50,000 – $500,000 USD - $500,000 – $5,000,000 USD - More than $5,000,000 USD primaryTargetMarket: type: string enum: - Commercial (businesses) - Retail (individual consumers) - Government - Other primaryTargetMarketOtherDescription: type: string description: Required if primaryTargetMarket is "Other". expectedCryptoMonthlyOperationCount: type: string enum: - 0-100 - 101-200 - 201< expectedFiatMonthlyOperationCount: type: string enum: - 0-100 - 100-200 - 201< operatingCountries: type: array minItems: 1 items: type: string highRiskIndustryExposure: type: boolean highRiskIndustries: type: array description: Required (min 1) if highRiskIndustryExposure is true. items: type: string enum: - Money Services Businesses (MSBs) - Cryptocurrency and Digital Asset Exchanges - Online Gambling and Gaming - Adult Entertainment - Cannabis and Marijuana - Firearms and Weapons - Pharmaceuticals and Controlled Substances - Political Organizations and PACs - Nonprofits and International Charities - Shell Companies and Complex Holding Structures - Precious Metals and Gems Dealers - High-Value Real Estate - Luxury Goods - Private ATM Operators - Pawn Shops - Import and Export Trade Finance highRiskActivityDescription: type: string description: Required if highRiskIndustryExposure is true. asiaExposure: type: boolean asiaExposureCountries: type: array description: Required (min 1) if asiaExposure is true. items: type: string capaProducts: type: array minItems: 1 items: type: string enum: - Stablecoin FX - International Payments regulatedCountries: type: array minItems: 1 items: type: string isUsMsb: type: boolean description: Required if country is US. usMsbCategories: type: array description: Required (min 1) if isUsMsb is true. items: type: string enum: - Money transmitter - Currency dealer or exchanger - Check casher - Issuer of traveler's checks or money orders - Provider of prepaid access - Seller of prepaid access - Dealer in foreign exchange - Virtual currency / asset provider - Other usMsbCategoriesOtherDescription: type: string description: Required if usMsbCategories includes "Other". msbVirtualAssetSubtype: type: string description: >- Required if usMsbCategories includes "Virtual currency / asset provider". msbServiceDescription: type: string description: Required if isUsMsb is true. mxLegalEntityType: type: string enum: - Personas Morales de nacionalidad mexicana - Persona Moral de Nacionalidad Extranjera - >- Persona Moral o Entidad referida en el Anexo 7-A de las Reglas de Carácter General description: Required if country is MX. mxAnnex7ASubtype: type: string description: Required if mxLegalEntityType is the Anexo 7-A option. mxVulnerableActivityOrLicense: type: boolean description: Required if country is MX. mxVulnerableActivityDescription: type: string description: Required if mxVulnerableActivityOrLicense is true. mxExpectedMonthlyOperationCount: type: string enum: - 0 to 100 - 101 to 200 - More than 201 description: Required if country is MX. mxEconomicActivity: type: string description: >- Required if country is MX. See Appendix — 136-entry official "giro" catalog. businessRegistrationDocument: $ref: '#/components/schemas/BusinessVerificationDocument' addressProofDocument: $ref: '#/components/schemas/BusinessVerificationDocument' bankStatementDocument: $ref: '#/components/schemas/BusinessVerificationDocument' sourceOfFundsDocument: allOf: - $ref: '#/components/schemas/BusinessVerificationDocument' description: >- AiPrise's Source of Funds slot (also labeled "Estado financiero" for EUR-market businesses) — optional, every market. directorsRegistry: $ref: '#/components/schemas/BusinessVerificationDocument' articlesOfIncorporation: $ref: '#/components/schemas/BusinessVerificationDocument' shareholdersRegistry: $ref: '#/components/schemas/BusinessVerificationDocument' taxRegistrationCertificate: $ref: '#/components/schemas/BusinessVerificationDocument' operatingLicenseDocument: allOf: - $ref: '#/components/schemas/BusinessVerificationDocument' description: Required if isUsMsb is true; optional otherwise. amlPolicy: allOf: - $ref: '#/components/schemas/BusinessVerificationDocument' description: Required if isUsMsb is true. beneficialControllerDeclaration: allOf: - $ref: '#/components/schemas/BusinessVerificationDocument' description: >- "Declaración Beneficiario Controlador Final" — optional, every market. relatedPersons: type: array minItems: 1 items: $ref: '#/components/schemas/RelatedPerson' SubmitKYBBusinessProfileHttpResponse: type: object properties: verificationId: type: string format: uuid description: Identity verification ID created for this submission. status: type: string enum: - NOT_STARTED - IN_PROGRESS - VERIFIED - REJECTED - REVIEW_NEEDED example: IN_PROGRESS externalResourceId: type: string description: >- AiPrise verification session id. Unset immediately after submission — the AiPrise call chain is processed asynchronously; poll GET /details for progress. submissionStage: type: string enum: - DRAFT - SUBMITTING - SUBMITTED description: >- Coarse progress of this KYB submission — always DRAFT immediately after this response, since the AiPrise call chain hasn't started yet. country: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object properties: success: type: boolean example: false code: type: string description: Machine-readable error code. message: type: string description: Human-readable error message. errors: type: array description: Optional per-field validation details. items: type: object properties: field: type: string message: type: string required: - success - code - message PhysicalAddress: type: object required: - streetLine1 - city - state - postalCode - country properties: streetLine1: type: string example: Av. Reforma 123 streetLine2: type: string city: type: string example: CDMX state: type: string example: CDMX postalCode: type: string example: '06600' country: type: string description: ISO 3166-1 alpha-2 country code. example: MX BusinessVerificationDocument: type: object required: - fileName - fileBase64 properties: fileName: type: string example: articles_of_incorporation.pdf fileBase64: type: string description: Base64-encoded file content. RelatedPerson: type: object description: >- A UBO/director/representative of the business. At least one related person is required. required: - firstName - lastName - dateOfBirth - roles - address - relationWithCompany - positionInCompany - taxId - sourceOfFunds - photoIdDocument - addressProofDocument properties: firstName: type: string middleName: type: string lastName: type: string dateOfBirth: type: string format: date example: '1990-01-01' phoneNumber: type: string example: '+525512345678' email: type: string format: email ownershipPercent: type: number minimum: 0 maximum: 100 sharesAllocated: type: number minimum: 0 roles: type: array minItems: 1 items: type: string enum: - AUTHORIZED_REPRESENTATIVE - BENEFICIAL_OWNER - CONTROLLING_PERSON - LEGAL_REPRESENTATIVE - DIRECTOR address: $ref: '#/components/schemas/PhysicalAddress' relationWithCompany: type: string description: Relationship to the company (e.g. "Founder", "Family member"). example: Founder positionInCompany: type: string description: Position/title at the company. example: CEO taxId: type: string description: Tax ID (SSN / RFC / ITIN). sourceOfFunds: type: array minItems: 1 items: type: string photoIdDocument: $ref: '#/components/schemas/BusinessVerificationDocument' addressProofDocument: $ref: '#/components/schemas/BusinessVerificationDocument' taxRegistrationDocument: allOf: - $ref: '#/components/schemas/BusinessVerificationDocument' description: CSF — optional, every market. beneficialOwnerDeclarationDocument: allOf: - $ref: '#/components/schemas/BusinessVerificationDocument' description: >- "Declaración Propietario Real" — only relevant for cross-border payments. accountStatementDocument: allOf: - $ref: '#/components/schemas/BusinessVerificationDocument' description: EUR-market only. securitySchemes: PartnerApiKey: type: apiKey in: header name: partner-api-key description: API key for the affiliated partner performing the request. ````