> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.withpersona.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server. # Integration Guide: KYB via API > Orchestrate business reports and owner verification through an API-first KYB flow. ## Solution overview * Silently orchestrates Persona's suite of [Know Your Business](https://withpersona.com/solutions/know-your-business) features, including running reports and verifying Business Owners * Can be configured to support a variety of countries and Owner verification types ## Pre-integration * [ ] Make sure your organization is set up with the requisite transaction and workflows! Reach out to your Persona team for support with this. * [ ] Review the intended flow with your Persona team and confirm which reports and verification checks will be run * [ ] Think about if you will be incorporating manual review on the business or are looking for a fully automated interaction (Persona can accommodate for either) ## Integration steps ### 1. Create the Transaction * Please ensure you’re including the `reference_id` property under the `attributes` object: this will be the value you use to identify the business in your own internal systems * Use your Production API key to create Production transactions, and your Sandbox API key to create Sandbox transactions #### Transaction fields Whether or not these fields are required will depend on your configuration of required and non-required inputs for each country. | Field | Type | Required | Description | | ------------------------------------- | ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | associated\_people | Array of Associated Person objects | false | Here's where you'll define the UBOs, directors, or other people associated with the business so they can undergo a KYC verification. | | business\_name | String | true | The business's name | | business\_tax\_identification\_number | String | true | The business's Tax Identification Number (e.g EIN) | | business\_physical\_address | Address object | false | The business's physical address | | business\_registered\_address | Address object | true | The business's incorporation or registered address | | documents | Array of Files | false | Any business documents you'd like to verify | | debug | String | false | For Sandbox verifications only: set as `passed` to pass verifications or `failed` to force-fail the verifications. By default, the verifications will pass. | #### Associated Person object fields Depending on your setup, you will either include all the information necessary to run a silent Database verification on every Associated Person ("DB Only"), or you will provide their name and email to the transaction and Persona will email them a link to verify themselves ("Inquiry only"). | Field | Type | Required? | Description | | --------------------------- | -------------- | ------------ | ------------------------------------------------------------------------------ | | account\_reference\_id | String | false | Your unique identifier for the user | | name\_first | String | true | First Name | | name\_last | String | true | Last name | | name\_middle | String | false | Middle name. May be used in reports, but not in the verifications themselves | | percentage\_ownership | Float | false | The percentage of the company the individual owns | | association | String | false | Freeform text field to represent this individual's association to the business | | birthdate | Date | DB only | Birthdate, in the format of `YYYY-MM-DD` | | address | Address object | DB only | An address object | | tax\_identification\_number | String | DB only | Tax Identification Number (e.g SSN) | | email\_address | String | Inquiry only | Email address | | phone\_number | String | false | Phone number | #### Address object fields | Field | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | street\_1 | String | Address street 1 | | street\_2 | String | Address street 2 | | city | String | Address city | | postal\_code | String | Address postal code | | subdivision | String | Address subdivision (state). Abides by [ISO 3166-2 standards](https://en.wikipedia.org/wiki/ISO_3166-2). | | country\_code | String | 2-letter country code. See Persona's list of supported countries [in your dashboard](https://app.withpersona.com/dashboard/resources/coverage-map/database). | #### Sample cURL commands You can use send your business data over in `application/json` or `multipart/form-data` formats. If you're uploading any business documents, we recommend using a `multipart/form-data` style of request. You'll need to add in your own values for the following: ``, `transaction_type_id`, `reference_id`, and the `email_address` fields for the associated people. **`JSON`** ```curl JSON curl -X POST https://api.withpersona.com/api/v1/transactions \ -H "Content-Type: application/json" \ -H 'Authorization: Bearer ' \ -d '{ "data": { "attributes": { "transaction_type_id": "", "reference_id": "", "fields": { "associated_people": [ { "name_first": "Alexander", "name_last": "Sample", "percentage_ownership": 75, "email_address": "", "association": "CEO", "birthdate": "1990-01-01", "address": { "street_1": "353 Sacramento Street", "street_2": "STE 1400", "city": "San Francisco", "subdivision": "CA", "postal_code": "94111", "country_code": "US" }, "tax_identification_number": "111111111" }, { "name_first": "Jennifer", "name_last": "Sample", "email_address": "", "association": "UBO", "percentage_ownership": 25, "birthdate": "1990-02-02", "address": { "street_1": "201 Post St", "city": "San Francisco", "subdivision": "CA", "postal_code": "94108", "country_code": "US" }, "tax_identification_number": "222222222" } ], "business_name": "My Sample Business", "business_tax_identification_number": "12-3456789", "business_physical_address": { "street_1": "353 Sacramento Street", "street_2": "STE 1400", "city": "San Francisco", "subdivision": "CA", "postal_code": "94111", "country_code": "US" }, "business_registered_address": { "street_1": "981 Mission St", "street_2": "", "city": "San Francisco", "subdivision": "CA", "postal_code": "94103", "country_code": "US" }, "documents": [ { "filename": "proof_of_address.pdf", "data": "" } ] } } } }' ``` **`Multipart Form`** ```curl Multipart Form curl -X POST https://withpersona.com/api/v1/transactions \ -H 'Authorization: Bearer ' \ --form 'data[attributes][transaction-type-id]=' \ --form 'data[attributes][fields][business_name]=My Sample Business' \ --form 'data[attributes][fields][business_tax_identification_number]=12-3456789' \ --form 'data[attributes][fields][business_physical_address][street_1]=353 Sacramento St' \ --form 'data[attributes][fields][business_physical_address][street_2]=Ste 1400' \ --form 'data[attributes][fields][business_physical_address][city]=San Francisco' \ --form 'data[attributes][fields][business_physical_address][subdivision]=CA' \ --form 'data[attributes][fields][business_physical_address][postal_code]=94111' \ --form 'data[attributes][fields][business_physical_address][country_code]=US' \ --form 'data[attributes][fields][business_registered_address][street_1]=981 Mission St' \ --form 'data[attributes][fields][business_registered_address][street_2]=' \ --form 'data[attributes][fields][business_registered_address][city]=San Francisco' \ --form 'data[attributes][fields][business_registered_address][subdivision]=CA' \ --form 'data[attributes][fields][business_registered_address][postal_code]=94103' \ --form 'data[attributes][fields][business_registered_address][country_code]=US' \ --form 'data[attributes][fields][associated_people][][name_first]=Alexander' \ --form 'data[attributes][fields][associated_people][][name_last]=Sample' \ --form 'data[attributes][fields][associated_people][][email_address]=' \ --form 'data[attributes][fields][associated_people][][association]=CEO' \ --form 'data[attributes][fields][associated_people][][birthdate]=1990-01-01' \ --form 'data[attributes][fields][associated_people][][percentage_ownership]=75' \ --form 'data[attributes][fields][associated_people][][address][street_1]=353 Sacramento St' \ --form 'data[attributes][fields][associated_people][][address][street_2]=STE 1400' \ --form 'data[attributes][fields][associated_people][][address][city]=San Francisco' \ --form 'data[attributes][fields][associated_people][][address][subdivision]=CA' \ --form 'data[attributes][fields][associated_people][][address][postal_code]=94111' \ --form 'data[attributes][fields][associated_people][][address][country_code]=US' \ --form 'data[attributes][fields][associated_people][][tax_identification_number]=111111111' \ --form 'data[attributes][fields][associated_people][][name_first]=Jennifer' \ --form 'data[attributes][fields][associated_people][][name_last]=Sample' \ --form 'data[attributes][fields][associated_people][][association]=UBO' \ --form 'data[attributes][fields][associated_people][][email_address]=' \ --form 'data[attributes][fields][associated_people][][birthdate]=1990-02-02' \ --form 'data[attributes][fields][associated_people][][percentage_ownership]=25' \ --form 'data[attributes][fields][associated_people][][address][street_1]=353 Sacramento St' \ --form 'data[attributes][fields][associated_people][][address][street_2]=STE 1400' \ --form 'data[attributes][fields][associated_people][][address][city]=San Francisco' \ --form 'data[attributes][fields][associated_people][][address][subdivision]=CA' \ --form 'data[attributes][fields][associated_people][][address][postal_code]=94111' \ --form 'data[attributes][fields][associated_people][][address][country_code]=US' \ --form 'data[attributes][fields][associated_people][][tax_identification_number]=222222222' \ --form 'data[attributes][fields][account_reference_id]=kyb_test_1' \ --form 'data[attributes][fields][documents][]=@path_to_file.png' ``` ### 2. Listen for the Transaction status We recommend listening to the `transaction.status-updated` webhook ([docs](/webhooks)) to know when to proceed with the business. You can alternatively make an API call to fetch the transaction ([docs](/api-reference/transactions/retrieve-a-transaction)) #### Transaction statuses Below are the default statuses that Persona includes in a KYB Transaction. You can make your own modifications as it fits your use case. To view and edit these statuses, click “… > Custom Statuses” on your transaction type’s page | Status name | Description | | -------------- | ----------------------------------------------------------------------------------------- | | `created` | Transaction has been created. | | `approved` | Transaction has been approved: you can proceed with the business. | | `declined` | Transaction has been declined: verifications unsuccessful or business otherwise declined. | | `needs_review` | Transaction is awaiting manual review. | | `errored` | Transaction has errored. | --- ## KYB Case and manual review Many KYB flows include some level of manual review. Persona streamlines manual review with our [Cases](https://withpersona.com/product/cases) product: every KYB transaction will create a case where you can view all of the business's verifications, reports, and associated people information all in once place. You can Approve or Decline a case from there, and that decision will reflect back on the transaction via Persona's orchestration engine (workflows). ![kyb](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/kyb.png)![kyb](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/kyb-2.png)![kyb](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/kyb-3.png)![kyb](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/kyb-4.png)