---
updatedAt: 2026-10-20T10:43:13.000Z
agentTools:
  projectIndex: https://harbor-developers.owlpay.com/llms.txt
---

# Start customer onboarding

Collects the complete KYB package (company profile, associated persons,
documents) and processes it asynchronously. Track progress via the GET
endpoint or `customer_onboarding.*` webhooks.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "OwlPay Harbor API",
    "description": "OwlPay Harbor API Documentation",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://harbor-sandbox.owlpay.com"
    }
  ],
  "tags": [
    {
      "name": "Customer Onboarding",
      "description": "Submit full KYB data for a business customer in one call; Harbor orchestrates verification asynchronously."
    }
  ],
  "components": {
    "securitySchemes": {
      "default": {
        "type": "apiKey",
        "name": "X-API-KEY",
        "in": "header",
        "description": "Please contact your customer service team to obtain your <b> API Key </b>."
      }
    }
  },
  "security": [
    {
      "default": []
    }
  ],
  "paths": {
    "/api/v1/customers/{customer_uuid}/onboarding": {
      "post": {
        "summary": "Start customer onboarding",
        "operationId": "startCustomerOnboarding",
        "description": "Collects the complete KYB package (company profile, associated persons,\ndocuments) and processes it asynchronously. Track progress via the GET\nendpoint or `customer_onboarding.*` webhooks.",
        "parameters": [
          {
            "in": "header",
            "name": "X-API-KEY",
            "description": "",
            "example": "{YOUR_API_KEY}",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "id": "onb_1234567890",
                      "customer_id": "{{customer_uuid}}",
                      "applicant": "company",
                      "status": "processing",
                      "submitted_at": null,
                      "created_at": "2026-06-12T06:35:50.000000Z",
                      "updated_at": "2026-06-12T06:35:50.000000Z"
                    }
                  },
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "onb_1234567890",
                          "description": "The onboarding ID (prefix `onb_`)."
                        },
                        "customer_id": {
                          "type": "string",
                          "example": "{{customer_uuid}}",
                          "description": "The ID of the customer this onboarding belongs to."
                        },
                        "applicant": {
                          "type": "string",
                          "example": "company",
                          "description": "The onboarding shape, derived from the customer type. Possible values: `company`, `individual`."
                        },
                        "status": {
                          "type": "string",
                          "example": "processing",
                          "description": "The onboarding status. Possible values: `processing`, `action_required`, `submitted`, `verified`, `declined`, `failed`. `action_required` covers everything to fix and resend, including a correctable rejection; `declined` is final — no resubmission."
                        },
                        "submitted_at": {
                          "type": "string",
                          "example": null,
                          "description": "ISO 8601 timestamp of when the onboarding was submitted for verification. Null until submitted."
                        },
                        "created_at": {
                          "type": "string",
                          "example": "2026-06-12T06:35:50.000000Z",
                          "description": "ISO 8601 timestamp of when the onboarding was created."
                        },
                        "updated_at": {
                          "type": "string",
                          "example": "2026-06-12T06:35:50.000000Z",
                          "description": "ISO 8601 timestamp of when the onboarding was last updated."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Customer Onboarding"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company": {
                    "type": "object",
                    "description": "The company (KYB) profile.",
                    "example": [],
                    "properties": {
                      "business_name": {
                        "type": "string",
                        "description": "The trading / doing-business-as name. Must not be greater than 255 characters.",
                        "example": "Acme"
                      },
                      "registration_number": {
                        "type": "string",
                        "description": "The company registration number. Must not be greater than 255 characters.",
                        "example": "REG123456"
                      },
                      "country": {
                        "type": "string",
                        "description": "ISO 3166-1 alpha-2 country code of incorporation. Must be 2 characters.",
                        "example": "TW"
                      },
                      "incorporation_date": {
                        "type": "string",
                        "description": "Incorporation date in YYYY-MM-DD format. Must be a valid date in the format <code>Y-m-d</code>.",
                        "example": "2020-01-01"
                      },
                      "type": {
                        "type": "string",
                        "description": "The company type. Possible values: `soleProprietorship`, `partnerships`, `limitedLiabilityCompany`, `corporation`, `corporationPublic`, `cooperative`, `nonProfitOrganization`, `stateOwnedCompany`, `trust`, `other`.",
                        "example": "limitedLiabilityCompany",
                        "enum": [
                          "soleProprietorship",
                          "partnerships",
                          "limitedLiabilityCompany",
                          "corporation",
                          "corporationPublic",
                          "cooperative",
                          "nonProfitOrganization",
                          "stateOwnedCompany",
                          "trust",
                          "other"
                        ]
                      },
                      "description": {
                        "type": "string",
                        "description": "A description of the company's business. Must not be greater than 1000 characters.",
                        "example": "Cross-border e-commerce of consumer electronics."
                      },
                      "industry": {
                        "type": "string",
                        "description": "Industry classification slug. Use a `value` from the `GET /countries/{country}/industries` lookup for the company country; Harbor translates it to the underlying SIC codes. Must not be greater than 191 characters.",
                        "example": "manufacture_computers"
                      },
                      "register_address": {
                        "type": "object",
                        "description": "The registered address.",
                        "example": [],
                        "properties": {
                          "street": {
                            "type": "string",
                            "description": "Street line of the registered address. Must not be greater than 255 characters.",
                            "example": "1 Main St"
                          },
                          "city": {
                            "type": "string",
                            "description": "City of the registered address. Must not be greater than 255 characters.",
                            "example": "Taipei"
                          },
                          "state": {
                            "type": "string",
                            "description": "State / province of the registered address. Must not be greater than 255 characters.",
                            "example": null,
                            "nullable": true
                          },
                          "postal_code": {
                            "type": "string",
                            "description": "Postal / ZIP code of the registered address. Must not be greater than 32 characters.",
                            "example": "100"
                          }
                        },
                        "required": [
                          "street",
                          "city",
                          "postal_code"
                        ]
                      },
                      "business_address": {
                        "type": "object",
                        "description": "The operating business address.",
                        "example": [],
                        "properties": {
                          "street": {
                            "type": "string",
                            "description": "Street line of the business address. Must not be greater than 255 characters.",
                            "example": "2 Biz Rd"
                          },
                          "city": {
                            "type": "string",
                            "description": "City of the business address. Must not be greater than 255 characters.",
                            "example": "Taipei"
                          },
                          "state": {
                            "type": "string",
                            "description": "State / province of the business address. Must not be greater than 255 characters.",
                            "example": null,
                            "nullable": true
                          },
                          "country": {
                            "type": "string",
                            "description": "ISO 3166-1 alpha-2 country code of the business address. Must be 2 characters.",
                            "example": "TW"
                          },
                          "postal_code": {
                            "type": "string",
                            "description": "Postal / ZIP code of the business address. Must not be greater than 32 characters.",
                            "example": "101"
                          }
                        },
                        "required": [
                          "street",
                          "city",
                          "country",
                          "postal_code"
                        ]
                      },
                      "phone_country_code": {
                        "type": "string",
                        "description": "(optional) ISO 3166-1 alpha-2 country code of the company phone. Defaults to the customer's phone_country_code; provide only to override it. Must be 2 characters.",
                        "example": "TW",
                        "nullable": true
                      },
                      "phone_number": {
                        "type": "string",
                        "description": "(optional) Company phone number. Defaults to the customer's phone_number; provide only to override it. Required if the customer has no phone. Must not be greater than 20 characters.",
                        "example": "912345678",
                        "nullable": true
                      },
                      "business_phone": {
                        "type": "object",
                        "description": "(optional) The business contact phone. Defaults to `company.phone` when omitted.",
                        "example": null,
                        "properties": {
                          "country": {
                            "type": "string",
                            "description": "ISO 3166-1 alpha-2 country code of the phone number. This field is required when <code>company.business_phone</code> is present. Must be 2 characters.",
                            "example": "TW"
                          },
                          "number": {
                            "type": "string",
                            "description": "Phone number, digits only. This field is required when <code>company.business_phone</code> is present. Must match the regex /^[0-9]+$/. Must not be greater than 32 characters.",
                            "example": "912345678"
                          }
                        },
                        "nullable": true
                      },
                      "url": {
                        "type": "string",
                        "description": "The company website URL. Must be a valid URL. Must not be greater than 255 characters.",
                        "example": "https://acme.example"
                      },
                      "has_bearer_shares": {
                        "type": "boolean",
                        "description": "Whether the company has bearer shares.",
                        "example": false
                      },
                      "purpose_of_registration": {
                        "type": "string",
                        "description": "Purpose of registering with Harbor. Possible values: `onlyReceiving`, `receiptAndPayment`.",
                        "example": "receiptAndPayment",
                        "enum": [
                          "onlyReceiving",
                          "receiptAndPayment"
                        ]
                      },
                      "estimated_number_of_transactions": {
                        "type": "integer",
                        "description": "Estimated number of transactions per month. Must be at least 0.",
                        "example": 100
                      },
                      "estimated_amount_of_transactions": {
                        "type": "integer",
                        "description": "Estimated USD amount of transactions per month. Must be at least 0.",
                        "example": 50000
                      },
                      "country_of_operation": {
                        "type": "array",
                        "description": "An ISO 3166-1 alpha-2 country code. Must be 2 characters.",
                        "example": [
                          "TW"
                        ],
                        "items": {
                          "type": "string"
                        }
                      },
                      "has_vasp_relationship": {
                        "type": "boolean",
                        "description": "Does this account have any relationship with other Virtual Asset Service Providers (VASPs)?.",
                        "example": false
                      },
                      "vasp_relationship_description": {
                        "type": "string",
                        "description": "(required if `has_vasp_relationship` is true) Describe the relationship with the other VASP(s). This field is required when <code>company.has_vasp_relationship</code> is <code>true</code>. Must not be greater than 1000 characters.",
                        "example": null,
                        "nullable": true
                      },
                      "source_of_funds": {
                        "type": "string",
                        "description": "Source of funds. Possible values: `BUSINESS_INCOME`, `CAPITAL_INJECTION`, `BANK_LOAN_OR_OTHER_BORROWINGS`, `INVESTMENT_INCOME`, `GOVERNMENT_GRANT`, `OTHER`.",
                        "example": "BUSINESS_INCOME",
                        "enum": [
                          "BUSINESS_INCOME",
                          "CAPITAL_INJECTION",
                          "BANK_LOAN_OR_OTHER_BORROWINGS",
                          "INVESTMENT_INCOME",
                          "GOVERNMENT_GRANT",
                          "OTHER"
                        ]
                      },
                      "source_of_funds_other": {
                        "type": "string",
                        "description": "(required if `source_of_funds` is `OTHER`) Description of the source of funds. This field is required when <code>company.source_of_funds</code> is <code>OTHER</code>. Must not be greater than 255 characters.",
                        "example": null,
                        "nullable": true
                      },
                      "transfers_funds_for_clients": {
                        "type": "boolean",
                        "description": "Do you transfer funds on behalf of your clients?.",
                        "example": true
                      },
                      "compliance_screening_explanation": {
                        "type": "string",
                        "description": "(optional) Explanation of the company's compliance screening program. Must not be greater than 1000 characters.",
                        "example": null,
                        "nullable": true
                      },
                      "tax_id": {
                        "type": "string",
                        "description": "The company tax / registration identification number (VAT, EIN, etc.). Must not be greater than 255 characters.",
                        "example": "EIN123456"
                      }
                    },
                    "required": [
                      "business_name",
                      "registration_number",
                      "country",
                      "incorporation_date",
                      "type",
                      "description",
                      "industry",
                      "register_address",
                      "business_address",
                      "url",
                      "has_bearer_shares",
                      "purpose_of_registration",
                      "estimated_number_of_transactions",
                      "estimated_amount_of_transactions",
                      "has_vasp_relationship",
                      "source_of_funds",
                      "transfers_funds_for_clients",
                      "tax_id"
                    ]
                  },
                  "associated_persons": {
                    "type": "array",
                    "description": "The associated persons. Exactly one `representative` is required; `applicant`, `equity_holder` and `controller` entries are added as applicable. Must have at least 1 items.",
                    "example": [
                      []
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "description": "The person type. Possible values: `representative`, `applicant`, `equity_holder`, `controller`.",
                          "example": "representative",
                          "enum": [
                            "representative",
                            "applicant",
                            "equity_holder",
                            "controller"
                          ]
                        },
                        "first_name": {
                          "type": "string",
                          "description": "First name. Must not be greater than 255 characters.",
                          "example": "Ada"
                        },
                        "last_name": {
                          "type": "string",
                          "description": "Last name. Must not be greater than 255 characters.",
                          "example": "Wang"
                        },
                        "id_type": {
                          "type": "string",
                          "description": "Identity document type. Possible values: `NATIONAL_ID`, `PASSPORT`, `DRIVER_LICENCE`, `RESIDENCE_PERMIT`.",
                          "example": "PASSPORT",
                          "enum": [
                            "NATIONAL_ID",
                            "PASSPORT",
                            "DRIVER_LICENCE",
                            "RESIDENCE_PERMIT"
                          ]
                        },
                        "id_number": {
                          "type": "string",
                          "description": "Identity document number. Must not be greater than 255 characters.",
                          "example": "A123456789"
                        },
                        "birthday": {
                          "type": "string",
                          "description": "Date of birth in YYYY-MM-DD format. Must be a valid date in the format <code>Y-m-d</code>.",
                          "example": "1990-01-01"
                        },
                        "gender": {
                          "type": "string",
                          "description": "Gender. Possible values: `M`, `F`.",
                          "example": "F",
                          "enum": [
                            "M",
                            "F"
                          ]
                        },
                        "nationality": {
                          "type": "string",
                          "description": "ISO 3166-1 alpha-2 nationality. Must be 2 characters.",
                          "example": "TW"
                        },
                        "position": {
                          "type": "string",
                          "description": "(required for `representative` and `controller`) Position in the company. Must not be greater than 255 characters.",
                          "example": "CEO",
                          "nullable": true
                        },
                        "email": {
                          "type": "string",
                          "description": "(required for `applicant` and `equity_holder`) Email address. Must be a valid email address. Must not be greater than 255 characters.",
                          "example": "ada@acme.example",
                          "nullable": true
                        },
                        "residential_address": {
                          "type": "object",
                          "description": "Residential address.",
                          "example": [],
                          "properties": {
                            "street": {
                              "type": "string",
                              "description": "Street line. Must not be greater than 255 characters.",
                              "example": "3 Home St"
                            },
                            "city": {
                              "type": "string",
                              "description": "City. Must not be greater than 255 characters.",
                              "example": "Taipei"
                            },
                            "state": {
                              "type": "string",
                              "description": "State / province. Must not be greater than 255 characters.",
                              "example": null,
                              "nullable": true
                            },
                            "country": {
                              "type": "string",
                              "description": "ISO 3166-1 alpha-2 country code. Must be 2 characters.",
                              "example": "TW"
                            },
                            "postal_code": {
                              "type": "string",
                              "description": "Postal / ZIP code. Must not be greater than 32 characters.",
                              "example": "100"
                            }
                          },
                          "required": [
                            "street",
                            "city",
                            "country",
                            "postal_code"
                          ]
                        },
                        "permanent_address": {
                          "type": "object",
                          "description": "(required for `representative` and `equity_holder`) Permanent address.",
                          "example": null,
                          "properties": {
                            "street": {
                              "type": "string",
                              "description": "Street line. This field is required when <code>associated_persons.*.permanent_address</code> is present. Must not be greater than 255 characters.",
                              "example": "3 Home St"
                            },
                            "city": {
                              "type": "string",
                              "description": "City. This field is required when <code>associated_persons.*.permanent_address</code> is present. Must not be greater than 255 characters.",
                              "example": "Taipei"
                            },
                            "state": {
                              "type": "string",
                              "description": "State / province. Must not be greater than 255 characters.",
                              "example": null,
                              "nullable": true
                            },
                            "country": {
                              "type": "string",
                              "description": "ISO 3166-1 alpha-2 country code. This field is required when <code>associated_persons.*.permanent_address</code> is present. Must be 2 characters.",
                              "example": "TW"
                            },
                            "postal_code": {
                              "type": "string",
                              "description": "Postal / ZIP code. This field is required when <code>associated_persons.*.permanent_address</code> is present. Must not be greater than 32 characters.",
                              "example": "100"
                            }
                          },
                          "nullable": true
                        },
                        "phone": {
                          "type": "object",
                          "description": "(required for `representative` and `equity_holder`) Phone.",
                          "example": null,
                          "properties": {
                            "country": {
                              "type": "string",
                              "description": "ISO 3166-1 alpha-2 country code of the phone number. This field is required when <code>associated_persons.*.phone</code> is present. Must be 2 characters.",
                              "example": "TW"
                            },
                            "number": {
                              "type": "string",
                              "description": "Phone number, digits only. This field is required when <code>associated_persons.*.phone</code> is present. Must match the regex /^[0-9]+$/. Must not be greater than 32 characters.",
                              "example": "900000000"
                            }
                          },
                          "nullable": true
                        },
                        "equity": {
                          "type": "number",
                          "description": "(required for `equity_holder`) Equity percentage held (0–100). Must be at least 0. Must not be greater than 100.",
                          "example": 35.5,
                          "nullable": true
                        },
                        "has_control": {
                          "type": "boolean",
                          "description": "(required for `equity_holder`) Whether the holder exercises control over the company.",
                          "example": true,
                          "nullable": true
                        },
                        "is_signer": {
                          "type": "boolean",
                          "description": "(required for `equity_holder`) Whether the holder is an authorized signer.",
                          "example": false,
                          "nullable": true
                        },
                        "relationship_established_at": {
                          "type": "string",
                          "description": "(required for `equity_holder`) Date the holding relationship was established, YYYY-MM-DD. Must be a valid date in the format <code>Y-m-d</code>.",
                          "example": "2020-02-02",
                          "nullable": true
                        },
                        "tax_jurisdiction_country": {
                          "type": "string",
                          "description": "(required for `equity_holder`) ISO 3166-1 alpha-2 tax jurisdiction country. Must be 2 characters.",
                          "example": "TW",
                          "nullable": true
                        },
                        "ssn": {
                          "type": "string",
                          "description": "(required for `equity_holder` when `nationality` is `US`) US Social Security Number, exactly 9 digits, no hyphens. Ignored for other person types. Must match the regex /^[0-9]{9}$/.",
                          "example": "123456789",
                          "nullable": true
                        },
                        "identity_files": {
                          "type": "array",
                          "description": "Identity document images for this person. Must have at least 1 items.",
                          "example": [
                            []
                          ],
                          "items": {
                            "type": "object",
                            "properties": {
                              "file_type": {
                                "type": "string",
                                "description": "Document type. Possible values: `NATIONAL_ID`, `PASSPORT`, `DRIVER_LICENCE`, `RESIDENCE_PERMIT`.",
                                "example": "PASSPORT",
                                "enum": [
                                  "NATIONAL_ID",
                                  "PASSPORT",
                                  "DRIVER_LICENCE",
                                  "RESIDENCE_PERMIT"
                                ]
                              },
                              "part": {
                                "type": "string",
                                "description": "Document side. Possible values: `FRONT`, `BACK`.",
                                "example": "FRONT",
                                "enum": [
                                  "FRONT",
                                  "BACK"
                                ]
                              },
                              "country": {
                                "type": "string",
                                "description": "ISO 3166-1 alpha-2 issuing country of the document. Must be 2 characters.",
                                "example": "TW"
                              },
                              "file": {
                                "type": "string",
                                "description": "Base64-encoded file content (max 10MB decoded).",
                                "example": "{{BASE64_FILE_CONTENT}}"
                              }
                            },
                            "required": [
                              "file_type",
                              "part",
                              "country",
                              "file"
                            ]
                          }
                        }
                      },
                      "required": [
                        "type",
                        "first_name",
                        "last_name",
                        "id_type",
                        "id_number",
                        "birthday",
                        "gender",
                        "nationality",
                        "residential_address",
                        "identity_files"
                      ]
                    }
                  },
                  "company_files": {
                    "type": "array",
                    "description": "Company documents, grouped by document type (each `file_type` may appear once). Must have at least 1 items.",
                    "example": [
                      []
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "file_type": {
                          "type": "string",
                          "description": "Document type. Possible values: `corporate_registration_documents`, `documents_of_corporate_governance_and_amendment`, `certificate_of_incumbency`, `organization_chart`, `proof_of_residential_address_of_the_ubo`, `proof_of_business_operating_address`, `initial_capital`, `income_source`, `business_license`, `executive_documents`, `financial_documents`, `compliance_documents`, `other_documentation`.",
                          "example": "corporate_registration_documents",
                          "enum": [
                            "corporate_registration_documents",
                            "documents_of_corporate_governance_and_amendment",
                            "certificate_of_incumbency",
                            "organization_chart",
                            "proof_of_residential_address_of_the_ubo",
                            "proof_of_business_operating_address",
                            "initial_capital",
                            "income_source",
                            "business_license",
                            "executive_documents",
                            "financial_documents",
                            "compliance_documents",
                            "other_documentation"
                          ]
                        },
                        "files": {
                          "type": "array",
                          "description": "Base64-encoded file content (max 10MB decoded).",
                          "example": [
                            "{{BASE64_FILE_CONTENT}}"
                          ],
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "file_type",
                        "files"
                      ]
                    }
                  }
                },
                "required": [
                  "company",
                  "associated_persons",
                  "company_files"
                ]
              }
            }
          }
        }
      },
      "parameters": [
        {
          "in": "path",
          "name": "customer_uuid",
          "description": "The ID of the customer.",
          "example": "cus_1234567890",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ]
    }
  }
}
```