KYC API

B2B Know Your Customer (KYC) verification for company accounts and identity validation.

Overview

The KYC API provides:

• Company Verification — Business entity validation
• Document Upload — Identity and business documents
• Shopify Integration — Sync with Shopify B2B companies
• Status Tracking — Real-time verification status

Base URL

https://api.huntrecht.com/api/v1/kyc

Required Scopes

Scope	Permission
kyc:read	View KYC status
kyc:write	Submit KYC documents

KYC Status Levels

Status	Description	Access Level
pending	Initial state	Limited
documents_submitted	Documents uploaded	Limited
in_review	Under review	Full
verified	Approved	Full
rejected	Documents rejected	Limited

Get KYC Status

GET /kyc/status

Retrieve current KYC verification status for a customer.

Query Parameters

Parameter	Type	Required	Description
customer_id	string	Yes	Customer ID

Example Request

kyc = client.kyc.get_status(customer_id="cust_abc123")

Example Response

{
  "data": {
    "customer_id": "cust_abc123",
    "status": "in_review",
    "level": "company_verified",
    "steps": [
      {
        "step": "email_verified",
        "status": "completed",
        "completed_at": "2026-01-05T10:00:00Z"
      },
      {
        "step": "company_info",
        "status": "completed",
        "completed_at": "2026-01-05T10:05:00Z"
      },
      {
        "step": "business_documents",
        "status": "completed",
        "completed_at": "2026-01-06T14:00:00Z"
      },
      {
        "step": "identity_verification",
        "status": "in_progress",
        "started_at": "2026-01-07T09:00:00Z"
      },
      {
        "step": "bank_verification",
        "status": "pending",
        "started_at": null
      }
    ],
    "shopify_company_id": "gid://shopify/Company/123",
    "submitted_at": "2026-01-07T09:00:00Z",
    "reviewed_at": null,
    "expires_at": "2026-07-07T00:00:00Z"
  }
}

Submit Company Information

POST /kyc/company

Submit company details for verification.

Request Body

Field	Type	Required	Description
customer_id	string	Yes	Customer ID
company_name	string	Yes	Legal company name
tax_id	string	Yes	Tax ID (EIN/VAT)
business_type	string	Yes	LLC, Corp, Partnership, etc.
date_of_incorporation	string	Yes	ISO 8601 date
address	object	Yes	Registered address
website	string	No	Company website
duns_number	string	No	D-U-N-S number

Example Request

kyc = client.kyc.submit_company({
    "customer_id": "cust_abc123",
    "company_name": "Acme Corporation",
    "tax_id": "12-3456789",
    "business_type": "LLC",
    "date_of_incorporation": "2018-03-15",
    "address": {
        "street": "123 Business Ave",
        "city": "Commerce City",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
    },
    "website": "https://acme.com"
})

Upload Documents

POST /kyc/documents

Upload verification documents.

Supported Document Types

Type	Description	Required
business_license	Business registration certificate	Yes
tax_certificate	Tax registration certificate	Yes
owner_id	Government-issued ID	Yes
bank_statement	Recent bank statement	Yes
financial_statement	Financial statements	No

Request Format

import requests

# Upload business license
files = {
    'document': ('business_license.pdf', open('license.pdf', 'rb'), 'application/pdf')
}

data = {
    'customer_id': 'cust_abc123',
    'document_type': 'business_license'
}

response = requests.post(
    "https://api.huntrecht.com/api/v1/kyc/documents",
    files=files,
    data=data,
    headers={"Authorization": f"Bearer {access_token}"}
)

result = response.json()

Example Response

{
  "data": {
    "document_id": "doc_abc123",
    "customer_id": "cust_abc123",
    "document_type": "business_license",
    "status": "pending_review",
    "uploaded_at": "2026-01-10T14:00:00Z",
    "reviewed_at": null,
    "expires_at": "2026-07-10T00:00:00Z"
  }
}

Identity Verification

POST /kyc/identity

Submit identity verification for company contacts.

Request Body

Field	Type	Required	Description
customer_id	string	Yes	Customer ID
first_name	string	Yes	First name
last_name	string	Yes	Last name
date_of_birth	string	Yes	ISO 8601 date
nationality	string	Yes	Country code
document_type	string	Yes	passport, drivers_license, national_id
document_number	string	Yes	Document number
document_expiry	string	Yes	Document expiry date

Example Request

kyc = client.kyc.submit_identity({
    "customer_id": "cust_abc123",
    "first_name": "John",
    "last_name": "Buyer",
    "date_of_birth": "1985-06-15",
    "nationality": "US",
    "document_type": "passport",
    "document_number": "123456789",
    "document_expiry": "2030-06-15"
})

Bank Account Verification

POST /kyc/bank

Link and verify a bank account.

Request Body

Field	Type	Required	Description
customer_id	string	Yes	Customer ID
bank_name	string	Yes	Bank name
account_name	string	Yes	Account holder name
account_number	string	Yes	Account number (encrypted)
routing_number	string	Yes	Routing number
account_type	string	Yes	checking, savings

Verification Methods

Method	Description	Timeline
micro_deposit	Small deposits verification	1-2 business days
plaid	Instant Plaid verification	Instant
manual	Upload bank statement	1-3 business days

kyc = client.kyc.link_bank({
    "customer_id": "cust_abc123",
    "bank_name": "First National Bank",
    "account_name": "Acme Corporation",
    "account_number": "XXXX1234",
    "routing_number": "021000021",
    "account_type": "checking",
    "verification_method": "plaid"
})

Shopify B2B Company Sync

The KYC process automatically syncs with Shopify B2B companies:

sequenceDiagram
    participant C as Customer
    participant H as Huntrecht KYC
    participant S as Shopify B2B
    
    C->>H: Submit KYC information
    H->>S: Create/Update Company
    H->>H: Verify documents
    H->>S: Sync verification status
    S-->>C: Company verified in Shopify

Webhook Events

Event	Description
kyc.submitted	KYC documents submitted
kyc.in_review	KYC under review
kyc.verified	KYC approved
kyc.rejected	KYC denied
kyc.expired	KYC verification expired

Rejected KYC Resolution

If KYC is rejected, the response includes reasons:

{
  "data": {
    "status": "rejected",
    "rejection_reasons": [
      {
        "field": "business_license",
        "reason": "Document expired",
        "action": "Upload current valid document"
      },
      {
        "field": "owner_id",
        "reason": "Photo unclear",
        "action": "Upload higher quality image"
      }
    ],
    "resubmit_deadline": "2026-01-25T00:00:00Z"
  }
}

Error Codes

Code	Description
CUSTOMER_NOT_FOUND	Customer ID not found
DOCUMENT_INVALID	Invalid document format
DOCUMENT_EXPIRED	Document has expired
KYC_ALREADY_VERIFIED	Customer already verified
VERIFICATION_PENDING	Another verification in progress

Next Steps

• Credit Risk Assessment
• B2B Onboarding Guide
• Bank Account Integration