Customer Init

Endpoint Overview

POST /api/v1/customer/

Description

This endpoint initializes a new customer profile in the Surepass KYC system. It creates a customer record with basic identification information that can be used for subsequent KYC verification processes. The customer initialization is the first step in the customer onboarding workflow and establishes the foundation for all future identity verification operations.

Key Benefits

Quick customer profile creation with minimal required information

Unique customer identifier generation for tracking all subsequent verifications

Seamless integration into existing onboarding workflows

Foundation for comprehensive KYC processes

Use Cases

Financial Services

Fintech

Insurance

Create new customer profiles during account opening processes

Initialize customer records before performing regulatory KYC checks

Establish digital identity foundations for banking customers

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT token
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
full_name	String	Yes	Given name
dob	String	Yes	Given DOB (`YYYY-MM-DD` format)
hosted	Boolean	No	Do Hosted KYC or not
scopes	List	No	Which kinds of KYC to allow
timedelta	Integer	No	Time for the token to be alive (min)
config	Object	No	Configuration for OCR thresholds
hosted_config	Object	No	Hosted KYC configuration
reference_id	String	Yes	Reference ID
mobile_number	String	Yes	Mobile number
client	String	Yes	Client identifier
masked_aadhaar	bool	No	Aadhaar masking option
webhook_url	URL	Yes	Webhook callback URL

Example Request

{
    "full_name": "John Doe",
    "dob": "1990-01-01"
}

Process Response

Response Parameters

The response follows the Customer Model structure with the following fields:

Parameter	Type	Required	Description
customer_id	String	Yes	Unique identifier of the Client
full_name	String	Yes	Full Name of the Customer
dob	Date	Yes	Date of Birth of the Customer
expiry	DateTime	Yes	Expiry Date
token	String	Yes	Token for Hosted KYC
hosted_link	String	Yes	Hosted Link

Example Successful Response

{
  "customer_id": "CUST123456",
  "full_name": "John Doe",
  "dob": "1990-01-01",
  "expiry": "2025-05-15T18:30:00Z",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "hosted_link": "https://kyc.surepass.io/hosted/CUST123456"
}

Possible Error Responses

Authentication Error

Validation Error

{
    "error": "unauthorized",
    "message": "Invalid or expired token provided"
}

This error occurs when the JWT token is invalid, expired, or not provided.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Collect customer information progressively to minimize friction during onboarding

Implement proper validation on your forms before submitting to the API

Display clear error messages to users when validation fails

Consider implementing a loading state while the API request is processing

Code Samples

cURL

Python

Node.js

Related APIs

Customer Update API: Updates existing customer information

Customer Retrieve API: Retrieves customer details using customer ID

Customer Delete API: Removes a customer profile from the system

Customer Verification API: Initiates verification processes for a customer

Compliance and Legal Considerations

When collecting and storing customer information, ensure compliance with relevant data protection regulations such as GDPR, CCPA, or local data privacy laws. The information collected through this API may be subject to Know Your Customer (KYC) and Anti-Money Laundering (AML) regulations depending on your industry and jurisdiction.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/customer/' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "full_name": "{{full_name}}", "dob": "{{dob}}" }'

{ "customer_id": "CUST123456", "full_name": "John Doe", "dob": "1990-01-01", "expiry": "2025-05-15T18:30:00Z", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "hosted_link": "https://kyc.surepass.io/hosted/CUST123456" }

Customer Init

Customer Init#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Customer Init

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples