Integration Guide: KYB via API

Solution overview

• Silently orchestrates Persona’s suite of 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 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 accomodate 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.

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”).

Address object fields

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: <api_token>, transaction_type_id, reference_id, and the email_address fields for the associated people.

1
curl -X POST https://api.withpersona.com/api/v1/transactions \
2
-H "Content-Type: application/json" \
3
-H 'Authorization: Bearer <api-token>' \
4
-d '{
5
  "data": {
6
    "attributes": {
7
      "transaction_type_id": "<your transaction ID>",
8
      "reference_id": "<your internal ID to identify the business>",
9
      "fields": {
10
        "associated_people": [
11
          {
12
            "name_first": "Alexander",
13
            "name_last": "Sample",
14
            "percentage_ownership": 75,
15
            "email_address": "<your email>",
16
            "association": "CEO",
17
            "birthdate": "1990-01-01",
18
            "address": {
19
              "street_1": "353 Sacramento Street",
20
              "street_2": "STE 1400",
21
              "city": "San Francisco",
22
              "subdivision": "CA",
23
              "postal_code": "94111",
24
              "country_code": "US"
25
            },
26
            "tax_identification_number": "111111111"
27
          },
28
          {
29
            "name_first": "Jennifer",
30
            "name_last": "Sample",
31
            "email_address": "<your email>",
32
            "association": "UBO",
33
            "percentage_ownership": 25,
34
            "birthdate": "1990-02-02",
35
            "address": {
36
              "street_1": "201 Post St",
37
              "city": "San Francisco",
38
              "subdivision": "CA",
39
              "postal_code": "94108",
40
              "country_code": "US"
41
            },
42
            "tax_identification_number": "222222222"
43
          }
44
        ],
45
        "business_name": "My Sample Business",
46
        "business_tax_identification_number": "12-3456789",
47
        "business_physical_address": {
48
          "street_1": "353 Sacramento Street",
49
          "street_2": "STE 1400",
50
          "city": "San Francisco",
51
          "subdivision": "CA",
52
          "postal_code": "94111",
53
          "country_code": "US"
54
        },
55
        "business_registered_address": {
56
          "street_1": "981 Mission St",
57
          "street_2": "",
58
          "city": "San Francisco",
59
          "subdivision": "CA",
60
          "postal_code": "94103",
61
          "country_code": "US"
62
        },
63
        "documents" [
64
          {
65
           "filename": "proof_of_address.pdf",
66
           "data": "<base64 encoded string of the file>"
67
          }
68
        ]
69
      }
70
    }
71
  }
72
}'

2. Listen for the Transaction status

We recommend listening to the transaction.status-updated webhook (docs) to know when to proceed with the business. You can alternatively make an API call to fetch the transaction (docs)

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

KYB Case and manual review

Many KYB flows include some level of manual review. Persona streamlines manual review with our 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).