> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/verify-business/kyc/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # Implement KYC > Implement Know Your Customer (KYC) verification through Socure to perform due diligence checks on people associated with a business as part of your underwriting process. Verify the identity of people associated with a business as part of your underwriting process. Middesk's Know Your Customer (KYC) capability uses [Socure](https://www.socure.com/) 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 After you sign your contract, Middesk does the following: * Configures your Socure account with your selected bundle and add-on modules * Provisions your Socure API credentials * Sets up default module configurations * Adds you as a user to your Middesk and Socure accounts ## Implement KYC #### 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) > **Note** > > Middesk typically handles module configuration during setup, so most customers don't need to make changes in the Socure portal. #### 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. #### Device risk module 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](https://developer.socure.com/docs/idplus/modules/sigma-device/sigma-device-overview) 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. #### Document verification module 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](https://developer.socure.com/docs/sdks/docv/overview) 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 #### Decision module If the [Decision module](https://developer.socure.com/guide/decision) 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. #### 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. Middesk verifies each person using the Socure modules configured for your account. See the Create A Business API reference for required KYC fields and the [person reference](/reference/person) for details about the `kyc` response schema. #### 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. **`An example response on the person`** ```json title="An example response on the person" { "object": "business", "id": "880a9600-4176-46c9-9a07-903104c675da", "review": { "object": "review", "id": "883fab97-e473-414a-be65-bd5a20899177", "created_at": "2022-05-13T22:25:24.971Z", "updated_at": "2022-05-13T22:25:25.169Z", "completed_at": null, "tasks": [ { "category": "kyc", "key": "kyc_decision", "label": "KYC", "message": "No risks were found with the associated people", "name": "kyc", "status": "warning", "sub_label": "Accept", "sources": [] } ] }, "people": [ { "object": "person", "name": "Kyle Mack", "submitted": true, "business_id": "880a9600-4176-46c9-9a07-903104c675da", "sources": [], "titles": [], "kyc": { "object": "kyc_result", "provider_external_id": "2cf895d3-83a0-4b2c-a5f2-aa49dd0fc591", "provider": "socure", "decision": "accept", "result": { "fields": "that", "depend": "on", "what": "bundles", "are": "enabled", "on": "your account :)" } } } ], "phone_numbers": [], "profiles": [], "registrations": [], "orders": [ { "id": "d2507100-c924-013a-7447-2cde48001122", "product": "kyc", "created_at": "2022-05-13T22:25:24.971Z", "updated_at": "2022-05-13T22:25:25.169Z", "completed_at": "2022-05-13T22:25:25.169Z", "status": "completed" } ], "industry_classification": null } ``` **`Response with DocV in initial KYC order`** ```json title="Response with DocV in initial KYC order" { "object": "business", "id": "880a9600-4176-46c9-9a07-903104c675da", "review": { "object": "review", "id": "883fab97-e473-414a-be65-bd5a20899177", "created_at": "2022-05-13T22:25:24.971Z", "updated_at": "2022-05-13T22:25:25.169Z", "completed_at": null, "tasks": [ { "category": "kyc", "key": "kyc_decision", "label": "KYC", "message": "No risks were found with the associated people", "name": "kyc", "status": "warning", "sub_label": "Accept", "sources": [] } ] }, "people": [ { "object": "person", "name": "Kyle Mack", "submitted": true, "business_id": "880a9600-4176-46c9-9a07-903104c675da", "sources": [], "titles": [], "kyc": { "object": "kyc_result", "provider_external_id": "2cf895d3-83a0-4b2c-a5f2-aa49dd0fc591", "provider": "socure", "decision": "accept", "result": { "fields": "that", "depend": "on", "what": "bundles", "are": "enabled", "on": "your account :)", "documentVerification": { "decision": { "name": "moderate", "value": "accept" }, "reasonCodes": [ "XXXXXX", "XXXXXX" ], "documentData": { "dob": "1980-01-01", "address": "330, NY 10001", "surName": "Doe", "fullName": "Jane Doe", "firstName": "Jane", "issueDate": "2015-01-01", "documentNumber": "11223344", "expirationDate": "2020-01-01" }, "documentType": { "type": "Drivers License", "state": "NY", "country": "US" } } } } } ], "phone_numbers": [], "profiles": [], "registrations": [], "orders": [ { "id": "d2507100-c924-013a-7447-2cde48001122", "product": "kyc", "created_at": "2022-05-13T22:25:24.971Z", "updated_at": "2022-05-13T22:25:25.169Z", "completed_at": "2022-05-13T22:25:25.169Z", "status": "completed" } ], "industry_classification": null } ``` **`Response with DocV step-up`** ```json title="Response with DocV step-up" { "object": "business", "id": "880a9600-4176-46c9-9a07-903104c675da", "review": { "object": "review", "id": "883fab97-e473-414a-be65-bd5a20899177", "created_at": "2022-05-13T22:25:24.971Z", "updated_at": "2022-05-13T22:25:25.169Z", "completed_at": null, "tasks": [ { "category": "kyc", "key": "kyc_decision", "label": "KYC", "message": "No risks were found with the associated people", "name": "kyc", "status": "warning", "sub_label": "Accept", "sources": [] } ] }, "people": [ { "object": "person", "name": "Kyle Mack", "submitted": true, "business_id": "880a9600-4176-46c9-9a07-903104c675da", "sources": [], "titles": [], "kyc": { "object": "kyc_result", "provider_external_id": "2cf895d3-83a0-4b2c-a5f2-aa49dd0fc591", "provider": "socure", "decision": "refer", "result": { "fields": "that", "depend": "on", "what": "bundles", "are": "enabled", "on": "your account :)" } }, "kyc_step_up": { "id": "7c4193c0-f09b-4850-98d4-bb78dfa06a54", "person_id": "05fa249c-8836-4f13-8d88-328d7aae9145", "reference_id": "48d4976a-a6b9-49ec-85cb-805c29962f91", "decision": "accept", "created_at": "2023-08-04T17:36:48.122Z", "updated_at": "2023-08-04T17:36:48.122Z", "response": { "referenceId": "48d4976a-a6b9-49ec-85cb-805c29962f91", "documentVerification": { "decision": { "name": "moderate", "value": "accept" }, "reasonCodes": [ "XXXXXX", "XXXXXX" ], "documentData": { "dob": "1980-01-01", "address": "330, NY 10001", "surName": "Doe", "fullName": "Jane Doe", "firstName": "Jane", "issueDate": "2015-01-01", "documentNumber": "11223344", "expirationDate": "2020-01-01" }, "documentType": { "type": "Drivers License", "state": "NY", "country": "US" } } } } } ], "phone_numbers": [], "profiles": [], "registrations": [], "orders": [ { "id": "d2507100-c924-013a-7447-2cde48001122", "product": "kyc", "created_at": "2022-05-13T22:25:24.971Z", "updated_at": "2022-05-13T22:25:25.169Z", "completed_at": "2022-05-13T22:25:25.169Z", "status": "completed" } ], "industry_classification": null } ``` ## 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](/create-orders) 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`** ```json title="A KYC-only request to /business" { "name": "A business Inc", "addresses": [ { "address_line1": "1234 Main", "city": "San Francisco", "state": "CA", "postal_code": "94109" } ], "people": [ { "first_name": "Kyle", "last_name": "Mack", "dob": "2001-12-31", "ssn": "123456789", "address_line1": "1234 Main", "address_line2": "Apt #5678", "city": "San Francisco", "state": "CA", "postal_code": "94109", "phone_number": "7075555555", "email": "example@example.com", // Only include if Device risk module is enabled "device_session_id": "1a74f8ba2be28cfc9020", // Only include if Document verification module is enabled "document_uuid": "2c126004-2a5e-41e2-a380-eddcdaadcf56" } ], "orders": [{"product": "kyc"}] } ``` ## 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`** ```json title="A PATCH request to add a KYC order to a business" { "people": [ { name: "Kurt Ruppel" }, { "first_name": "Kyle", "last_name": "Mack", "dob": "2001-12-31", "ssn": "123456789", "address_line1": "1234 Main", "address_line2": "Apt #5678", "city": "San Francisco", "state": "CA", "postal_code": "94109", "phone_number": "7075555555", "email": "example@example.com", // Only include if Device risk module is enabled "device_session_id": "1a74f8ba2be28cfc9020", // Only include if Document verification module is enabled "document_uuid": "2c126004-2a5e-41e2-a380-eddcdaadcf56" } ] } ``` > **Get a demo** > > Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access. > Implement Know Your Customer (KYC) verification through Socure to perform due diligence checks on people associated with a business as part of your underwriting process.