> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # KYC/KYB Verification > US banking regulations require financial institutions to collect and verify information about their customers. Synctera's verification solution provides identity and watchlist checks for personal and business customers. ## Overview US banking regulations require a Customer Identification Program (CIP) — commonly known as *know your customer* (KYC) and *know your business* (KYB). Synctera's verification solution runs identity and watchlist checks for personal and business customers and records the results as `verification` objects. **A verification** represents a category of checks performed on a customer. The combined outcome of all verifications sets the customer's `verification_status`, which gates money movement — a customer must reach `ACCEPTED` to transact. A CIP program requires: * **Data collection** — name, date of birth, address, and government-issued ID. * **Disclosures** — notifying customers about the collection and retention of data. * **Verification** — confirming the collected information is current, valid, and accurate. * **Ongoing monitoring** — checking the customer against known watchlists over time. Key characteristics: * **Categorized** — each verification has a `verification_type` (`IDENTITY`, `WATCHLIST`, `DOCUMENT_VERIFICATION`, `RELATED_ENTITIES`, `MANUAL_REVIEW`). * **Detailed** — a `details` array records the individual attribute-level checks and their outcomes. * **Status-driven** — the customer's `verification_status` reflects all verifications; only `ACCEPTED` customers can move money. * **Recursive for businesses** — verifying a business also verifies its beneficial owners, owning businesses, and officers. To move money, all customers must undergo KYC or KYB verification. ## Prerequisites This guide assumes you have: * Created a [personal customer](/docs/create-a-personal-customer) or [business customer](/docs/create-a-business) * Recorded a [disclosure](/docs/record-disclosure-acceptance) You should also be familiar with: * [Need to Know — Environments](/reference/need-to-know#environments) * [Need to Know — Authentication](/reference/need-to-know#authentication) ## The verification object A verification represents one category of checks on a customer. The `details` array holds the individual checks that make up that category. | Field | Description | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Unique identifier (read-only). | | `person_id` / `business_id` | The customer the verification applies to. | | `verification_type` | The category of check: `IDENTITY`, `WATCHLIST`, `DOCUMENT_VERIFICATION`, `RELATED_ENTITIES`, or `MANUAL_REVIEW`. | | `result` | The outcome of this verification (e.g. `ACCEPTED`, `REVIEW`, `REJECTED`). | | `details` | Attribute-level checks, each with a `label`, `description`, and `result` (`PASS`, `WARN`, `FAIL`). | | `required_documents` | Documents you must collect from the customer to advance the case review (e.g. `ID_DOCUMENT`, `ADDRESS_VERIFICATION`, `SSN_VERIFICATION`). Populated when the outcome requires documentary evidence to proceed. | | `verification_time` | When the verification ran. | | `creation_time` / `last_updated_time` | Timestamps (read-only). | An `IDENTITY` verification bundles the checks pertaining to a customer's identity — here, name, address, SSN, and email were all verified: ```json theme={"system"} { "id": "05e2ddf3-d172-450e-9cf3-7a34f76a414f", "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "verification_type": "IDENTITY", "result": "ACCEPTED", "details": [ { "label": "Customer Identification Program (CIP)", "description": "Full name, address, and SSN/ITIN can be resolved to the individual", "result": "PASS" }, { "label": "Address", "description": "Address can be resolved to the individual", "result": "PASS" }, { "label": "Email", "description": "Email address is more than 2 years old", "result": "PASS" } ], "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" } ``` Watchlist checks are represented by the `WATCHLIST` verification type: ```json theme={"system"} { "id": "a24a16a2-4711-4486-8049-787462c61ffc", "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "verification_type": "WATCHLIST", "result": "ACCEPTED", "details": [ { "label": "Watchlist", "description": "Global Watchlist sources selected are not correlated with the input identifiers", "result": "PASS" } ], "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" } ``` ## Verification status A customer's `verification_status` is the outcome of all verifications performed on them. New customers start as `UNVERIFIED`; the field lives on the [person](/reference/createperson) and [business](/reference/createbusiness) resources. A successful verify request moves the customer out of `UNVERIFIED` into one of: | Status | Meaning | | -------------- | ----------------------------------------------------------------------------------------------- | | `PENDING` | Verification is in progress (common for businesses). | | `PROVISIONAL` | Partially verified or verified with restrictions. | | `ACCEPTED` | The customer is verified and can move money. | | `REVIEW` | Verification ran and identified issues requiring review. | | `VENDOR_ERROR` | Verification did not run due to an unexpected error. | | `REJECTED` | The customer was rejected and should be blocked from certain actions (e.g. opening an account). | Any status other than `ACCEPTED` opens a case in the [Synctera Case Manager](/docs/kyc-cases-fintechs) for a compliance officer to review. **Suggested handling by outcome:** | Outcome | Recommended action | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ACCEPTED` | Continue onboarding (e.g. [create an account](/docs/create-accounts-guide)). | | `REVIEW` | Tell the user their application is under manual review. Continue onboarding but do not open an account until the case resolves to `ACCEPTED` (or inform them if `REJECTED`). | | `REJECTED` | Notify the applicant they were turned down and stop the flow. | | `VENDOR_ERROR` | Retry via API; if unresolved, follow the `REVIEW` path. | If a customer is not initially accepted: * Offer them a chance to review and correct the information they entered. * After corrections, call `POST /v0/verifications/verify` again to re-verify. * You may also verify using the customer's government ID via [document verification](/docs/document-verification). * If they make **no** changes, do not re-run KYC/KYB — let the case be reviewed instead. * If they make changes and are still not accepted, stop and route to manual review. * Re-verifications triggered by the end-user (`customer_initiated: true`) count against any [customer-initiated verification limit](#limiting-customer-initiated-verifications). Two statuses fall outside the typical path: * `PENDING` — business results may not be immediately available. Subscribe to the `BUSINESS.VERIFICATION_OUTCOME.UPDATED` webhook. * `PROVISIONAL` — indicates an entity has been partially verified. ### Collecting required documents When a verification cannot be resolved from the submitted data alone, the verification object's `required_documents` array tells you exactly which documents to collect from the end customer to advance the case. Read this field and prompt the customer for the corresponding documents. | `required_document` | What to collect | Accepted documents | | ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `ID_DOCUMENT` | Proof of identity | Government-issued driver's license, state ID, or passport | | `ADDRESS_VERIFICATION` | Proof of legal address | Driver's license or state ID with address, or a utility bill, bank statement, or pay stub issued within 60 days, or a lease agreement | | `SSN_VERIFICATION` | Proof of Social Security Number | Social Security card, recent tax return (e.g. 1040), or a W-2 or 1099 | Where you submit the collected documents depends on the value: * **`ID_DOCUMENT`** — complete the [document verification](/docs/document-verification) flow, which validates the customer's government-issued ID and steps them up for review. * **`ADDRESS_VERIFICATION` and `SSN_VERIFICATION`** — upload the supporting documents to the [documents API](/docs/document-storage-guide). For example, if a verification returns `"required_documents": ["SSN_VERIFICATION"]`, collect an SSN document (such as a Social Security card or W-2) from your end customer and upload it via the [documents API](/docs/document-storage-guide). If multiple values are present, collect a document for each and submit it to the appropriate destination above. ```json theme={"system"} { "id": "05e2ddf3-d172-450e-9cf3-7a34f76a414f", "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "verification_type": "IDENTITY", "result": "REVIEW", "required_documents": ["SSN_VERIFICATION"], "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" } ``` Collect only the documents named in `required_documents`. Submitting unrelated documents will not advance the case. ### Limiting customer-initiated verifications Banks and FinTechs can configure a maximum number of customer-initiated `IDENTITY` verifications per person over a rolling 3-month window, reducing synthetic-identity risk, stolen-identity abuse, and excessive vendor costs. A verification counts against the limit **only** when the request includes `customer_initiated: true` — i.e. the end-user themselves triggered it (for example, by tapping a "Verify my identity" button). Verifications triggered by the bank, FinTech, or Synctera are not counted. When the limit is reached, further `customer_initiated: true` requests are rejected; route those customers to manual review or support. To enable this protection, contact Synctera to configure `max_customer_initiated_verifications` for your tenant. ## Verifying a customer Once the required information is collected, initiate verification with [POST /v0/verifications/verify](/reference/verify) and the customer's ID: ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/verifications/verify \ --data-binary ' { "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "customer_ip_address": "184.233.47.237", "customer_consent": true, "customer_initiated": true }' ``` To verify a business, specify `business_id` instead of `person_id`: ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/verifications/verify \ --data-binary ' { "business_id": "eaa9807f-8cda-4308-8244-90c11b1b43a5", "customer_ip_address": "184.233.47.237", "customer_consent": true }' ``` Set `customer_initiated` to `true` when the end-user triggers the request (e.g. a "Verify my identity" button). This enforces any tenant-configured limit on how many times a customer can re-verify. See [Limiting customer-initiated verifications](#limiting-customer-initiated-verifications). Consent must come directly from the customer. ## Example: verify a personal customer Create the customer record with [POST /v0/persons](/reference/createperson): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/persons \ --data-binary ' { "first_name": "Christopher", "middle_name": "James", "last_name": "Albertson", "dob": "1985-06-14", "email": "chris@example.com", "phone_number": "+16045551212", "ssn": "456-78-9999", "legal_address": { "address_line_1": "123 Main St.", "city": "Beverly Hills", "state": "CA", "postal_code": "90210", "country_code": "US" }, "is_customer": true, "status": "ACTIVE" }' ``` See the [Create a Personal Customer](/docs/create-a-personal-customer) guide for details. Display and record a disclosure informing the customer that their data will be shared with a third party for identity verification, using [POST /v0/disclosures](/reference/createdisclosure): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/disclosures \ --data-binary ' { "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "type": "KYC_DATA_COLLECTION", "version": "1.0", "event_type": "ACKNOWLEDGED", "disclosure_date": "2022-03-17T17:04:34Z" }' ``` See the [Record Disclosure Acceptance](/docs/record-disclosure-acceptance) guide for details. With consent captured, verify the customer with [POST /v0/verifications/verify](/reference/verify): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/verifications/verify \ --data-binary ' { "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "customer_ip_address": "184.233.47.237", "customer_consent": true }' ``` The response contains an overall `verification_status` and an array of the verifications performed: ```json theme={"system"} { "verification_status": "ACCEPTED", "verifications": [ { "id": "05e2ddf3-d172-450e-9cf3-7a34f76a414f", "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "verification_type": "IDENTITY", "result": "ACCEPTED", "details": [ { "label": "Customer Identification Program (CIP)", "description": "Full name, address, and SSN/ITIN can be resolved to the individual", "result": "PASS" }, { "label": "Address", "description": "Address can be resolved to the individual", "result": "PASS" }, { "label": "Email", "description": "Email address is more than 2 years old", "result": "PASS" } ], "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" }, { "id": "a24a16a2-4711-4486-8049-787462c61ffc", "person_id": "7ef75751-e372-4c12-9b02-b9e4b1faaac9", "verification_type": "WATCHLIST", "result": "ACCEPTED", "details": [ { "label": "Watchlist", "description": "Global Watchlist sources selected are not correlated with the input identifiers", "result": "PASS" } ], "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" } ] } ``` The customer is now `ACCEPTED` and ready for the [account creation guide](/docs/create-accounts-guide). ## Example: verify a business customer Complete due diligence on the business before opening an account. This example models a business with a single beneficial owner: ```mermaid theme={"system"} %%{init: {"fontFamily": "sans-serif"}}%% graph TD A[Beneficial Owner] --> B(Your New Business) ``` Create the business with [POST /v0/businesses](/reference/createbusiness): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/businesses \ --data-binary ' { "entity_name": "Your New Business", "website": "https://example.com", "phone_number": "+16045551212", "legal_address": { "address_line_1": "123 Main St.", "city": "San Francisco", "state": "CA", "postal_code": "94105", "country_code": "US" }, "structure": "CORPORATION", "formation_date": "2000-01-01", "formation_state": "DE", "ein": "99-9999999", "is_customer": true, "status": "ACTIVE" }' ``` Create the [beneficial owner](https://en.wikipedia.org/wiki/Beneficial_ownership) as a person with [POST /v0/persons](/reference/createperson): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/persons \ --data-binary ' { "first_name": "Christopher", "middle_name": "James", "last_name": "Albertson", "dob": "1985-06-14", "email": "chris@example.com", "phone_number": "+16045551212", "ssn": "456-78-9999", "legal_address": { "address_line_1": "456 Main St.", "city": "San Francisco", "state": "CA", "postal_code": "94105", "country_code": "US" }, "is_customer": false, "status": "ACTIVE" }' ``` Use the returned person `id` to [create a relationship](/reference/createrelationship) with the business via `BENEFICIAL_OWNER_OF`: ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/relationships \ --data-binary ' { "from_person_id": "{BENEFICIAL_OWNER_ID}", "relationship_type": "BENEFICIAL_OWNER_OF", "to_business_id": "{BUSINESS_ID}", "additional_data": { "percent_ownership": 50 } }' ``` Create KYC data collection disclosures for each owner before verifying. See the [Record Disclosure Acceptance](/docs/record-disclosure-acceptance) guide. Verify the business — and all related entities — with [POST /v0/verifications/verify](/reference/verify): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/verifications/verify \ --data-binary ' { "business_id": "{BUSINESS_ID}", "customer_consent": true }' ``` Verifying a business initiates KYC and KYB for **all** entities: the business and its beneficial owner. The business is now verified and ready for the [account creation guide](/docs/create-accounts-guide). ## Example: verify a business with a complex ownership structure To satisfy regulatory requirements you must model the full ownership structure — beneficial owners, holding corporations, officers, and directors. This example adds a holding company (which owns the business) and an officer of that holding company: ```mermaid theme={"system"} %%{init: {"fontFamily": "sans-serif"}}%% graph TD D[Owner] --> C A[Officer] --> B(Holding Company) B --> C(Your New Business) ``` Create the primary business with [POST /v0/businesses](/reference/createbusiness) (see [Create a Business Customer](/docs/create-a-business) for details). Set `is_customer` to `true` to indicate it will be a customer: ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/businesses \ --data-binary ' { "entity_name": "Your New Business", "website": "https://example.com", "phone_number": "+16045551212", "legal_address": { "address_line_1": "123 Main St.", "city": "San Francisco", "state": "CA", "postal_code": "94105", "country_code": "US" }, "structure": "CORPORATION", "formation_date": "2000-01-01", "formation_state": "DE", "ein": "99-9999999", "is_customer": true, "status": "ACTIVE" }' ``` Create the beneficial owner with [POST /v0/persons](/reference/createperson), then link them via a `BENEFICIAL_OWNER_OF` [relationship](/reference/createrelationship): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/relationships \ --data-binary ' { "from_person_id": "{BENEFICIAL_OWNER_ID}", "relationship_type": "BENEFICIAL_OWNER_OF", "to_business_id": "{BUSINESS_ID}", "additional_data": { "percent_ownership": 50 } }' ``` Represent the owning business by creating another business (not a customer) with [POST /v0/businesses](/reference/createbusiness), then link it with an `OWNER_OF` relationship: ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/relationships \ --data-binary ' { "from_business_id": "{HOLDING_COMPANY_ID}", "relationship_type": "OWNER_OF", "to_business_id": "{BUSINESS_ID}", "additional_data": { "percent_ownership": 50 } }' ``` Because the holding company controls a portion of the business, model its officers. Create the officer as a person, then link them to the holding company with a `MANAGING_PERSON_OF` relationship: ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/relationships \ --data-binary ' { "from_person_id": "{OFFICER_ID}", "relationship_type": "MANAGING_PERSON_OF", "to_business_id": "{HOLDING_COMPANY_ID}", "additional_data": { "title": "OFFICER" } }' ``` Create KYC data collection disclosures for each owner before verifying. See the [Record Disclosure Acceptance](/docs/record-disclosure-acceptance) guide. Verify the business and all related entities with [POST /v0/verifications/verify](/reference/verify): ```shell theme={"system"} curl \ -X POST \ -H "Authorization: Bearer $apikey" \ -H 'Content-Type: application/json' \ https://api.synctera.com/v0/verifications/verify \ --data-binary ' { "business_id": "{BUSINESS_ID}", "customer_consent": true }' ``` Verifying the business initiates KYC and KYB for **all** entities: the business, the holding company, its officers, and the beneficial owners. The response includes an overall `verification_status`, the verifications performed, and a `RELATED_ENTITIES` verification summarizing the outcomes for the beneficial owner, holding company, and officer: ```json theme={"system"} { "verification_status": "ACCEPTED", "verifications": [ { "id": "598dd41e-733c-4fee-b8e7-a71de41881ef", "business_id": "eaa9807f-8cda-4308-8244-90c11b1b43a5", "verification_type": "RELATED_ENTITIES", "result": "ACCEPTED", "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" }, { "id": "05e2ddf3-d172-450e-9cf3-7a34f76a414f", "business_id": "eaa9807f-8cda-4308-8244-90c11b1b43a5", "verification_type": "IDENTITY", "result": "ACCEPTED", "details": [ { "label": "Business Name", "description": "Match identified to the submitted Business Name", "result": "PASS" }, { "label": "Office Address", "description": "Match identified to the submitted Office Address", "result": "PASS" } ], "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" }, { "id": "a24a16a2-4711-4486-8049-787462c61ffc", "business_id": "eaa9807f-8cda-4308-8244-90c11b1b43a5", "verification_type": "WATCHLIST", "result": "ACCEPTED", "details": [ { "label": "Watchlist", "description": "No Watchlist hits were identified", "result": "PASS" } ], "verification_time": "2022-03-14T18:34:59.91272Z", "creation_time": "2022-03-14T18:34:59.918188Z", "last_updated_time": "2022-03-14T18:34:59.918188Z" } ] } ``` ## Best practices A customer cannot move money until their `verification_status` is `ACCEPTED`. Do not open accounts or enable transactions for customers in `REVIEW`, `PENDING`, or `REJECTED`. * **Collect and disclose first** — gather all required fields and record the KYC data collection disclosure before verifying. * **Model the full ownership tree** — link every beneficial owner, owning business, and officer before verifying a business; one call verifies them all. * **Handle each outcome deliberately** — follow the suggested actions per status; open a review case rather than blindly re-running KYC. * **Guard re-verification** — send `customer_initiated: true` for user-triggered retries and respect the configured limit. * **Subscribe to webhooks** — watch `BUSINESS.VERIFICATION_OUTCOME.UPDATED` for asynchronous `PENDING` business results. ## Related guides Onboard a person before verifying them. Model business ownership before running KYB. Capture the KYC data collection disclosure. Step up customers flagged for review. Submit results from your own KYC/KYB vendor. Continuously screen verified customers. ## API reference * [Run a verification](/reference/verify) * [List verifications](/reference/listverifications1) * [Create a person](/reference/createperson) * [Create a business](/reference/createbusiness) * [Create a relationship](/reference/createrelationship) * [Create a disclosure](/reference/createdisclosure)