Verify a business (KYB)

Implement KYC

Verify the identify of people associated with a business as part of your underwriting process. Middesk’s Know Your Customer (KYC) capability uses Socure to automatically check each associated person’s Personal Identification Information (PII) and return an approval or rejection decision based on your configured Socure risk modules.

Prerequisites

Once your contract is signed, Middesk will:

  • Configure your Socure account with your selected bundle and add-on modules
  • Provision your Socure API credentials
  • Set up default module configurations
  • Add you as a user to your Middesk and Socure accounts

Implement KYC

1

Access your Socure portal (optional)

After Middesk provisions your account, optionally log in to the Socure portal to:

  • Add additional users to your Socure account
  • Review or adjust the default module settings
  • Configure Decision module criteria (if that module is enabled for your account)
Middesk typically handles module configuration during setup, so most customers don’t need to make changes in the Socure portal.
2

Implement optional modules

The modules available to you depend on your Socure bundle and add-ons configured during setup. Only implement the modules that are enabled for your account.

If your account includes the Socure Device risk module or Document verification module, follow these steps to implement them. The Decision module works automatically if enabled.

If the Sigma Device risk module is enabled for your account, you can link a device to a person’s identity using device fingerprinting technology. Implement one of Socure’s client-side SDKs to generate a Device Session ID. See Socure’s device fingerprinting guide to learn how to set up the SDK.

If you have this module enabled, include the device_session_id parameter when submitting a person to enable device risk analysis as part of your KYC check.

Use the Document Verification module to verify government-issued identity documents like passports and driver’s licenses. This optional module confirms the document is authentic, validates that the extracted personal information matches what you submitted, and compares the ID photo to a selfie.

To set up this module:

  1. Confirm that this module is enabled for your account.
  2. Implement Socure’s Predictive DocV SDK to capture documents and generate a document_uuid.
  3. Configure the SDK with "verificationLevel": 1 (see the Socure DocV SDK reference for implementation details).

To use document verification in your initial KYC order, include the document_uuid from Socure’s SDK when you create or update a person on a business. The verification results appear in the kyc object on the person, including the document decision, extracted document data, and reason codes.

If your initial KYC check returns a risky result, you can request additional document verification by sending a PATCH request with the document_uuid to an existing person. This runs document verification independently and returns:

  • The step-up results in the kyc_step_up object on the person
  • A new decision in kyc_step_up.decision that may override the initial KYC decision

If the Decision module is enabled for your account, it provides automated accept, reject, or refer recommendations for each person based on your risk criteria.

The API returns a decision for each person and an aggregated business-level insight based on all individual decisions.

3

Submit a KYC order

Submit a KYC order on a business to run due diligence checks on the people associated with that business.

Create a business with the people array populated with complete PII (Personal Identification Information) for each person you want to verify. Include {"product": "kyc"} in the orders array to request KYC verification.

Each person is verified using the Socure modules configured for your account. See the Create A Business API reference for required KYC fields and the person reference for details about the kyc response schema.

4

Review the KYC results

Once the KYC order completes, check the kyc object on each person for their individual decision (accept, reject, or refer) and detailed results based on your enabled modules. You’ll also see an aggregated KYC insight at the business level in the review.tasks array that summarizes the overall risk assessment.

1{
2  "object": "business",
3  "id": "880a9600-4176-46c9-9a07-903104c675da",
4  "review": {
5    "object": "review",
6    "id": "883fab97-e473-414a-be65-bd5a20899177",
7    "created_at": "2022-05-13T22:25:24.971Z",
8    "updated_at": "2022-05-13T22:25:25.169Z",
9    "completed_at": null,
10    "tasks": [
11      {
12        "category": "kyc",
13        "key": "kyc_decision",
14        "label": "KYC",
15        "message": "No risks were found with the associated people",
16        "name": "kyc",
17        "status": "warning",
18        "sub_label": "Accept",
19        "sources": []
20      }
21    ]
22  },
23  "people": [
24    {
25      "object": "person",
26      "name": "Kyle Mack",
27      "submitted": true,
28      "business_id": "880a9600-4176-46c9-9a07-903104c675da",
29      "sources": [],
30      "titles": [],
31      "kyc": {
32        "object": "kyc_result",
33        "provider_external_id": "2cf895d3-83a0-4b2c-a5f2-aa49dd0fc591",
34        "provider": "socure",
35        "decision": "accept",
36        "result": {
37          "fields": "that",
38          "depend": "on",
39          "what": "bundles",
40          "are": "enabled",
41          "on": "your account :)"
42        }
43      }
44    }
45  ],
46  "phone_numbers": [],
47  "profiles": [],
48  "registrations": [],
49  "orders": [
50    {
51      "id": "d2507100-c924-013a-7447-2cde48001122",
52      "product": "kyc",
53      "created_at": "2022-05-13T22:25:24.971Z",
54      "updated_at": "2022-05-13T22:25:25.169Z",
55      "completed_at": "2022-05-13T22:25:25.169Z",
56      "status": "completed"
57    }
58  ],
59  "industry_classification": null
60}

Submit a KYC-only order

Middesk supports flexible ordering to match your onboarding workflow. You can run KYC checks before, after, or independently from identity verification orders.

Include a KYC order in your initial business creation request by adding {"product": "kyc"} to the orders array. Provide the business details and include complete PII for each person in the people array.

Once the KYC order completes, you can add an identity order to the same business if needed.

A KYC-only request to /business
1{
2  "name": "A business Inc",
3  "addresses": [
4    {
5      "address_line1": "1234 Main",
6      "city": "San Francisco",
7      "state": "CA",
8      "postal_code": "94109"
9    }
10  ],
11  "people": [
12    {
13      "first_name": "Kyle",
14      "last_name": "Mack",
15      "dob": "2001-12-31",
16      "ssn": "123456789",
17      "address_line1": "1234 Main",
18      "address_line2": "Apt #5678",
19      "city": "San Francisco",
20      "state": "CA",
21      "postal_code": "94109",
22      "phone_number": "7075555555",
23      "email": "example@example.com",
24      // Only include if Device risk module is enabled
25      "device_session_id": "1a74f8ba2be28cfc9020",
26      // Only include if Document verification module is enabled
27      "document_uuid": "2c126004-2a5e-41e2-a380-eddcdaadcf56"
28    }
29  ],
30  "orders": [{"product": "kyc"}]
31}

Add a KYC order after identity verification

If you’ve already completed an identity verification, you can add KYC checks by updating the business’s people array with the individuals you want to verify. Include their complete PII in a PATCH request to the business.

A PATCH request to add a KYC order to a business
1{
2  "people": [
3  	{ name: "Kurt Ruppel" },
4    {
5      "first_name": "Kyle",
6      "last_name": "Mack",
7      "dob": "2001-12-31",
8      "ssn": "123456789",
9      "address_line1": "1234 Main",
10      "address_line2": "Apt #5678",
11      "city": "San Francisco",
12      "state": "CA",
13      "postal_code": "94109",
14      "phone_number": "7075555555",
15      "email": "example@example.com",
16      // Only include if Device risk module is enabled
17      "device_session_id": "1a74f8ba2be28cfc9020",
18      // Only include if Document verification module is enabled
19      "document_uuid": "2c126004-2a5e-41e2-a380-eddcdaadcf56"
20    }
21  ]
22}
Get a demo
Contact your account manager or contact sales to inquire about access.