CKYC Create and Update API

Introduction

The CKYC Create/Update API enables financial institutions to create or update KYC records of individuals and Legal entities in the CKYC registry.

It supports both record creation (INDIVIDUAL_CREATE, LEGAL_ENTITY_CREATE) and record modification (INDIVIDUAL_UPDATE, LEGAL_ENTITY_UPDATE) using structured JSON requests.

The API accepts detailed applicant information including personal details, identity documents, addresses, related persons, and images (in Base64 format).

On successful submission, a batch ID is returned, while conflicts or errors are reported with appropriate status codes.

This API ensures standardized, compliant, and seamless integration of customer KYC data across financial systems.

Note: Please use your dedicated server endpoint in case this module is deployed on your server.

This document describes the two APIs required to upload CKYC records to the Signzy CKYC platform:

API Details

Login API – authenticates the user and issues an authentication token.

File Upload API – submits one or more CKYC records (Individual or Legal Entity) for processing.

Authentication Overview

The Signzy CKYC platform uses cookie-based authentication with double-submit CSRF protection. Successful login sets two cookies rather than returning a token in the response body:

Cookie	Contents	Attributes
ckyc_jwt	The JWT used to authenticate every subsequent request.	HttpOnly, Path=/, Secure and SameSite per environment. Not readable by JavaScript.
ckyc_csrf	A random CSRF token (double-submit value).	Readable (not HttpOnly); echo it back in the x-csrf-token header on every mutating request.

HTTPS environments: over HTTPS the cookies are issued with the __Host- prefix (__Host-ckyc_jwt, __Host-ckyc_csrf). Over plain HTTP (local/dev) the prefix is dropped. Read the actual cookie name from the login response's Set-Cookie headers rather than hard-coding it.

Two integration styles are supported:

Server-to-server (Bearer) — recommended for API clients. Read the JWT value from the Set-Cookie: ckyc_jwt=<jwt> header returned by the Login API, then send it as Authorization: Bearer <jwt> on the File Upload API. A pure Bearer caller carries no cookie, so CSRF validation does not apply and no x-csrf-token header is required. This is the simplest path for automated integrations.

Cookie + CSRF (browser / cookie-jar clients). Retain the cookies from login and send them on subsequent requests. Because the ckyc_jwt cookie is present, every mutating request (including File Upload) must also send the ckyc_csrf value in the x-csrf-token header, or the request is rejected with 403.

Field lists and enum codes in this document are taken from the authoritative CERSAI template schema (config/cersai/individual/template.json) and the CKYC field-enums reference. Every field accepted by the API is enumerated below; every enum field's full code list is included in Section 5.

3.1 Login API request

curl --location 'http://{{baseUrl}}/ckyc/user/login' \
  --include \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "[email protected]",
    "password": "********"
  }'

Use --include (or -c cookies.txt to persist a cookie jar) so you can capture the Set-Cookie headers, since the token is no longer returned in the response body.

3.2 Login API response:

On success, the platform returns HTTP 200 with an empty JSON body and delivers authentication via Set-Cookie headers:

HTTP/1.1 200 OK
Set-Cookie: ckyc_jwt=<jwt_token>; HttpOnly; Path=/; SameSite=...
Set-Cookie: ckyc_csrf=<csrf_token>; Path=/; SameSite=...

{}

For Server-to-server integration: extract the ckyc_jwt value and use it as the Bearer token for the File Upload API.

For Cookie-based integration: keep both cookies; send the cookies plus the ckyc_csrf value in the x-csrf-token header on upload.

Default token validity is 1 hour. Admin can change the validity period in the Admin portal.

CKYC Upload/Update API

POST https://{{productionBaseUrl}}/ckyc/ckyc-upload/file/upload

POST https://{{PreproductionBaseUrl}}/ckyc/ckyc-upload/file/upload

Header

Header	Value
accept	application/json, application/text, application/plain
content-type	application/json
authorization	Bearer <jwt_token> — server-to-server style. <jwt_token> is the ckyc_jwt value read from the Login response's Set-Cookie header.
x-csrf-token	(Cookie-based clients only) The ckyc_csrf cookie value. Required when authenticating by cookie; omit when using a Bearer token.

Note: Send either an Authorization: Bearer header or the login cookies + x-csrf-token — not a mix.

Request Body

Top-level request body

{
  "recordType": "INDIVIDUAL_CREATE",
  "records": [ { /* record object */ } ],
  "sourceId": "4b4820f9-2eb3-402f-9959-87fe987cf775",
  "pipelineTemplateId": "b0e31fa2-1644-4e05-8a97-76c0e8330615",
  "flags": { /* processing flags — see Refer section 3.0.1 */ },
  "callback_url": ""
}

Field	Type	Mandatory	Description
recordType	string	Yes	Batch type. One of: INDIVIDUAL_CREATE, INDIVIDUAL_UPDATE, LEGAL_ENTITY_CREATE, LEGAL_ENTITY_UPDATE.
records	array	Yes	Array of record objects (≥ 1). Each object represents one CKYC record.
sourceId	UUID	Yes	Source identifier. Maps the incoming payload to an admin-configured Input Mapping that translates the raw record fields to the CERSAI schema. Must reference an existing source for the admin of the calling user.
pipelineTemplateId	UUID	Yes	Pipeline template identifier defining which pipeline stages will be executed for this batch. Must reference an existing template; the API returns 400 if the template does not exist.
flags	object	No	Processing flags controlling dedupe, image-quality, ReKYC, and download-analyzer behaviour. See Refer section 2.1 Defaults apply when omitted.
callback_url	string	No	URL on which you want the subsequent periodic responses

flags object

All flags are optional. Defaults shown below.

Flag	Type	Default	Description
workflow	boolean	false	When true, it takes the data from CKYC (CERSAI/FI’s DB if dedupe check is there), and does comparison with Fresh KYC data submitted. Then it decides as per below criteria: i) No mismatch: No Action needed, workflow stops. ii) Mismatch: Fresh KYC data pushed to CKYC Update flow. iii) No CKYC found, KYC data pushed to CKYC Create flow
reKycEnabled	boolean	false	Enable ReKYC flow. When true: (a) every record must include ovdDetails.email, otherwise the request fails with 400; (b) workflow is forced to true. It’ll initiate the reKYC flow, where CKYC data would be considered as latest KYC data to complete the ReKYC, if Address mismatch found, then confirmation mail would be sent to the customer.

Note: sourceId and pipelineTemplateId are issued during onboarding.

Contact the Signzy CKYC team to receive the sourceId and pipelineTemplateId for your production environment.

4.1 record object

Each entry of records[] contains five sections:

S.No.	Section	Type	Description
4.1.1	ovdDetails	object	Officially Valid Document used to identify the applicant.
4.1.2	personalDetails	object	Demographic, address, contact, KYC-verification details.
4.1.3	identityDetails	array	One entry per identity document.
4.1.4	relatedPersonDetails	array	Related person(s) — required for minor accounts, legal entities, etc.
4.1.5	imageDetails	array	Image attachments.

4.1.1 ovdDetails object (optional)

Note: Not to be used if you are using it for CKYC Create/Update on standalone basis.

Field	Type	Description
ovdType	string	OVD type code. See section 5.1.
ovdNumber	string	OVD number (e.g., PAN string or Aadhaar last 4).
ckycNumber	string \| null	Existing 14-digit CKYC number, if known. Use null for new records.
authFactorType	string	Authentication factor type code. Section 5.2.
authFactorValue	string	Value of the auth factor (e.g., DOB in DD-MM-YYYY, or mobile number).

4.1.2 personalDetails object

Note: Mandatory/Non mandatory guidelines to be followed as per CERSAI compliance. Refer Bulk File Structure_Version 1.3 of CERSAI docs.

#	Field	Type	Notes / Enum
1	record_type	string	"20"
2	line_number	Integer	Row sequence within record
3	application_type	string	Refer to section 5.3 01 - CKYC Create, 03 - CKYC Update
4	branch_code	string	Branch identifier of uploading FI
5	applicant_entity_name_update_flag	string	Update flag — Enum Refer section 5.4 (only for application_type = 03)
6	personal_entity_details_update_flag	string	Update flag — Enum Refer section 5.4
7	address_details_update_flag	string	Update flag — Enum Refer section 5.4
8	contact_details_update_flag	string	Update flag — Enum Refer section 5.4
9	other_details_or_deceased_information	string	Enum Refer section 5.5 (update only)
10	kyc_verification_update_flag	string	Update flag — Enum Refer section 5.4
11	identity_details_update_flag	string	Update flag — Enum Refer section 5.4
12	related_person_details_update_flag	string	Update flag — Enum Refer section 5.4
14	image_details_update_flag	string	Update flag — Enum Refer section 5.4
15	constitution_type	string	Enum Refer section 5.6
16	constitution_type_others	string	Required when constitution_type = R (Others)
18	account_type	string	Enum Refer section 5.7
19	ckyc_no_or_fi_reference_no	string	FI reference number — must be unique within the batch and would be generated by FI for CKYC Create. Pass CKYC No for CKYC Update in this parameter.
20	applicant_name_prefix	string	E.g., Mr, Mrs, Ms, Dr
21	applicant_first_name	string
22	applicant_middle_name	string
23	applicant_last_name	string
24	name_of_the_entity	string	Required for legal entities
25	applicant_maiden_name_prefix	string
26	applicant_maiden_first_name	string
27	applicant_maiden_middle_name	string
28	applicant_maiden_last_name	string
29	applicant_maiden_full_name	string	Concatenated maiden name (alt. to prefix/first/middle/last)
30	flag_father_or_spouse_name	string	Enum Refer section 5.8
31	father_or_spouse_name_prefix	string
32	father_or_spouse_first_name	string
33	father_or_spouse_middle_name	string
34	father_or_spouse_last_name	string
35	father_or_spouse_full_name	string	Concatenated (alt. form)
36	mother_name_prefix	string
37	mother_first_name	string
38	mother_middle_name	string
39	mother_last_name	string
40	mother_full_name	string	Concatenated (alt. form)
41	gender	string	Enum Refer section 5.9
42	marital_status	string	Enum Refer section 5.10
43	nationality	string	ISO 3166-1 alpha-2 — Enum Refer section 5.21
44	occupation_type	string	Free text (e.g., Employed, Self-Employed, Student, Retired)
45	date_of_birth_or_incorporation	string	DD-MM-YYYY by default. If the template is configured from the Admin module, pass it as per the Template ID.
46	place_of_incorporation	string	Legal entity only
47	date_of_commencement_of_business	string	DD-MM-YYYY by default. Legal entity only. If the template is configured from the Admin module, pass it as per the Template ID.
48	country_of_incorporation	string	ISO alpha-2 — Enum Refer section 5.21
49	country_of_residence_tax_laws	string	ISO alpha-2 — Enum Refer section 5.21
50	deceased_date	string	DD-MM-YYYY, by default format. Only when reporting deceased. If the template is configured from the Admin module, pass it as per the Template ID.
51	tin_or_gst_registration_number	string	TIN / GST number
52	tin_issuing_country	string	ISO alpha-2 — Enum Refer section 5.21
53	pan_or_form_60	string	PAN of applicant (or Form 60 marker)
54	residential_status	string	Enum Refer section 5.11
55	differently_abled_status_flag	string	Enum Refer section 5.12
56	type_of_impairment	string	Enum Refer section 5.13 (required if Refer section 5.12 = 1)
57	percentage_of_impairment	string	Numeric string 0–100
58	udid_number	string	UDID number (Unique Disability ID)
59	city_or_place_of_birth	string
60	address_type	string	Enum Refer section 5.14 (permanent/registered address)
61	address_line_1	string
62	address_line_2	string
63	address_line_3	string
64	city_town_village	string
65	district	string
66	state_ut	string	Enum Refer section 5.20
67	country	string	ISO alpha-2 — Enum Refer section 5.21
68	pincode	string	6-digit Indian PIN or foreign postal code
69	proof_of_address	string	Enum Refer section 5.17 (for permanent address)
70	proof_of_address_registered_others	string	Description when POA = 99 (Legal Entity Others)
71	proof_identity_address_same	string	Enum Refer section 5.18 (Y/N)
72	local_address_type	string	Enum Refer section 5.15 (current address)
73	current_address_line1	string
74	current_address_line2	string
75	current_address_line3	string
76	current_address_city	string
77	current_address_district	string
78	current_address_state	string	Enum Refer section 5.20
79	current_address_country	string	ISO alpha-2 — Enum Refer section 5.21
80	current_address_pincode	string
81	proof_of_address_current	string	Enum Refer section 5.17 (for current address)
82	address_in_jurisdiction_same_as_current	string	Enum Refer section 5.18 (Y/N)
83	address_in_jurisdiction_type	string	Enum Refer section 5.16
84	address_in_jurisdiction_line1	string
85	address_in_jurisdiction_line2	string
86	address_in_jurisdiction_line3	string
87	address_in_jurisdiction_city	string
88	address_in_jurisdiction_state	string	Enum Refer section 5.20
89	address_in_jurisdiction_country	string	ISO alpha-2 — Enum Refer section 5.21
90	address_in_jurisdiction_zip	string
91	proof_of_address_jurisdiction	string	Enum Refer section 5.17
92	residence_telephone_std_code	string
93	residence_telephone_number	string
94	office_telephone_std_code	string
95	office_telephone_number	string
96	mobile_isd_code	string	e.g., +91
97	mobile_number	string	Primary mobile
98	fax_std_code	string
99	fax_number	string
100	email_id	string	Primary email
101	remarks	string	Free-text remarks
102	date_of_declaration	string	DD-MM-YYYY
103	place_of_declaration	string
104	kyc_verification_date	string	DD-MM-YYYY
105	type_of_document_submitted	string	Enum Refer section 5.19
106	kyc_verification_name	string	KYC officer name
107	kyc_verification_designation	string
108	kyc_verification_branch	string
109	kyc_verification_emp_code	string
114	identity_verification_flag	string	Enum Refer section 5.30 (legal entity)
115	deceased_flag	string	Enum Refer section 5.31 (update only)
118	mobile_no_2_isd_code	string	Secondary mobile ISD
119	mobile_no_2	string	Secondary mobile
120	email_id_2	string	Secondary email
121	ucic	string	Unique Customer Identification Code at Bank level.

4.1.3 identityDetails — full field list (array)

#	Field	Type	Notes / Enum
1	record_type	string	Constant "30"
2	line_number	number	Sequence number within the record (starts at 1)
3	identification_type	string	Enum Refer section 5.22
4	identity_number	string	Identity number; last 4 digits only for Aadhaar (codes E, H, I)
5	other_identity_description	string	Description when "Other" identity type is used
6	expiry_date	string	DD-MM-YYYY (if applicable) by default format. If the template is configured from the Admin module, pass it as per the Template ID.
7	identity_proof_submitted	string	Y / N — whether physical proof submitted
8	identity_verification_status	string	Enum Refer section 5.23
9	filler_1	string	Remark field. Pass “” if nothing is there to fill.
10	filler_2	string	Remark field. Pass “” if nothing is there to fill.
11	filler_3	string	Remark field. Pass “” if nothing is there to fill.
12	filler_4	string	Remark field. Pass “” if nothing is there to fill.

4.1.4 relatedPersonDetails — full field list (array)

#	Field	Type	Notes / Enum
1	record_type	string	Constant "40"
2	line_number	number	Sequence within record
3	type_of_relationship	string	Enum Refer section 5.24
4	addition_deletion_related_person	string	Enum Refer section 5.25
5	kyc_number_related_person	string	Related person's CKYC number, if available
6	related_person_name_prefix	string
7	related_person_first_name	string
8	related_person_middle_name	string
9	related_person_last_name	string
10	related_person_maiden_name_prefix	string
11	related_person_maiden_first_name	string
12	related_person_maiden_middle_name	string
13	related_person_maiden_last_name	string
14	related_person_father_spouse_name	string	Enum Refer section 5.26
15	related_person_father_spouse_name_prefix	string
16	related_person_father_spouse_first_name	string
17	related_person_father_spouse_middle_name	string
18	related_person_father_spouse_last_name	string
19	related_person_mother_name_prefix	string
20	related_person_mothers_first_name	string
21	related_person_mothers_middle_name	string
22	related_person_mothers_last_name	string
23	date_of_birth	string	DD-MM-YYYY by default format. If the template is configured from the Admin module, pass it as per the Template ID.
24	gender	string	Enum Refer section 5.9
25	marital_status	string	Enum Refer section 5.10
26	nationality	string	ISO alpha-2 — Enum Refer section 5.21
27	relative_residential_status	string	Enum Refer section 5.11
28	differently_abled_status_flag	string	Enum Refer section 5.12
29	type_of_impairment	string	Enum Refer section 5.13
30	percentage_of_impairment	string	0–100
31	udid_number	string
32	country_of_birth	string	ISO alpha-2 — Enum Refer section 5.21
33	city_place_of_birth	string
34	pan_form_60	string	PAN
35	proof_of_aadhaar	string	Aadhaar (last 4 digits)
36	voter_id_card	string	Voter ID number
37	nrega_job_card	string
38	passport_number	string
39	foreign_national_id	string
40	driving_licence_number	string
41	national_population_register_letter	string
42	e_kyc_authentication	string
43	offline_verification_of_aadhaar	string
44	image_photograph	string	Base64-encoded photograph or Accessible URL link
45	image_POI_POA_proof	string	Base64-encoded or Accessible URL link of POI/POA document
46	image_current_address_proof	string	Base64-encoded or Accessible URL link of current-address proof
47	proof_identity_address_line1	string	POI/POA address
48	proof_identity_address_line2	string
49	proof_identity_address_line3	string
50	proof_identity_address_city	string
51	proof_identity_address_district	string
52	proof_identity_address_pincode	string
53	proof_identity_address_state	string	Enum Refer section 5.20
54	proof_identity_address_country	string	ISO alpha-2 — Enum Refer section 5.21
55	proof_submitted_for_identity_address	string	Enum Refer section 5.17
56	proof_identity_address_same_as_current	string	Enum Refer section 5.18 (Y/N)
57	current_address_line1	string	Current address
58	current_address_line2	string
59	current_address_line3	string
60	current_address_city	string
61	current_address_district	string
62	current_address_state	string	Enum Refer section 5.20
63	current_address_country	string	ISO alpha-2 — Enum Refer section 5.21
64	current_address_pincode	string
65	proof_of_address_current_address	string	Enum Refer section 5.17
66	residence_telephone_std_code	string
67	residence_telephone_number	string
68	office_telephone_std_code	string
69	office_telephone_number	string
70	mobile_isd_code	string
71	mobile_number	string
72	fax_std_code	string
73	fax_number	string
74	email_id	string
75	date_of_declaration	string	DD-MM-YYYY by default format. If the template is configured from the Admin module, pass it as per the Template ID.
76	place_of_declaration	string
77	kyc_verification_date	string	DD-MM-YYYY by default format. If the template is configured from the Admin module, pass it as per the Template ID.
78	document_submitted_type	string	Enum Refer section 5.19
79	kyc_verification_name	string
80	kyc_verification_designation	string
81	kyc_verification_branch	string
82	kyc_verification_emp_code	string
83	organisation_name	string
84	organisation_code	string
85	din_number	string	DIN — required for Directors
86	remarks	string
87	related_person_type_others_description	string	Required when type_of_relationship = 15 (Other)
88	filler_2	string	Pass “”
89	filler_3	string	Pass “”
90	filler_4	string	Pass “”

4.1.5 imageDetails — full field list (array)

#	Field	Type	Notes / Enum
1	record_type	string	Constant "70"
2	line_number	number	Sequence within record
3	image	string	Base64-encoded image bytes or Accessible URL
4	image_type	string	Enum Refer section 5.27
5	global_local_image_flag	string	Enum Refer section 5.28
6	branch_code	string	Branch code (optional)
7	filler1	string	Pass ""
8	filler2	string	Pass ""
9	filler3	string	Pass ""

4.2 Request body

Complete INDIVIDUAL_CREATE payload with one record and three image objects (02, 04, 06). Replace <BASE64_ENCODED_IMAGE_DATA> with the actual base64 string and substitute the sourceId / pipelineTemplateId UUIDs issued to your organisation.

  {
  "recordType": "INDIVIDUAL_CREATE",
  "sourceId": "4b4820f9-2eb3-402f-9959-87fe987cf775",
  "pipelineTemplateId": "b0e31fa2-1644-4e05-8a97-76c0e8330615",
  "flags": {
    "workflow": false,
    "runUploadAgent": false,
    "imageQualityAnalysis": true,
    "imageVerification": true,
    "maskAadhaarNumber": true,
    "autoImageSizeCorrector": true,
    "reKycEnabled": false
  },
  "records": [
    {
      "ovdDetails": {
        "ovdType": "P",
        "ovdNumber": "ABCDM1001N",
        "ckycNumber": null,
        "authFactorType": "01",
        "authFactorValue": "20-03-1988"
      },
      "personalDetails": {
        "application_type": "01",
        "applicant_entity_name_update_flag": "",
        "personal_entity_details_update_flag": "",
        "address_details_update_flag": "",
        "contact_details_update_flag": "",
        "kyc_verification_update_flag": "",
        "identity_details_update_flag": "",
        "related_person_details_update_flag": "",
        "image_details_update_flag": "",
        "other_details_or_deceased_information": "",
        "constitution_type": "01",
        "constitution_type_others": "",
        "account_type": "01",
        "ckyc_no_or_fi_reference_no": "56403745410601",
        "applicant_name_prefix": "Mr",
        "applicant_first_name": "Karan",
        "applicant_middle_name": "",
        "applicant_last_name": "Mehta",
        "name_of_the_entity": "",
        "applicant_maiden_name_prefix": "",
        "applicant_maiden_first_name": "",
        "applicant_maiden_middle_name": "",
        "applicant_maiden_last_name": "",
        "flag_father_or_spouse_name": "01",
        "father_or_spouse_name_prefix": "Mr",
        "father_or_spouse_first_name": "Sanjay",
        "father_or_spouse_middle_name": "",
        "father_or_spouse_last_name": "Mehta",
        "mother_name_prefix": "Mrs",
        "mother_first_name": "Reena",
        "mother_middle_name": "",
        "mother_last_name": "Mehta",
        "gender": "M",
        "marital_status": "Married",
        "nationality": "IN",
        "occupation_type": "Employed",
        "date_of_birth_or_incorporation": "20-03-1988",
        "place_of_incorporation": "",
        "date_of_commencement_of_business": "",
        "country_of_incorporation": "IN",
        "country_of_residence_tax_laws": "IN",
        "tin_or_gst_registration_number": "",
        "tin_issuing_country": "",
        "pan_or_form_60": "ABCDM1001N",
        "residential_status": "01",
        "differently_abled_status_flag": "0",
        "type_of_impairment": "",
        "percentage_of_impairment": "",
        "udid_number": "",
        "city_or_place_of_birth": "Bengaluru",
        "address_type": "01",
        "address_line_1": "45 Aundh Road",
        "address_line_2": "Bopodi",
        "address_line_3": "",
        "city_town_village": "Bengaluru",
        "district": "Bengaluru Urban",
        "state_ut": "KA",
        "country": "IN",
        "pincode": "560001",
        "proof_of_address": "01",
        "proof_of_address_registered_others": "",
        "proof_identity_address_same": "N",
        "local_address_type": "",
        "current_address_line1": "12 Baner Lane",
        "current_address_line2": "Baner",
        "current_address_line3": "",
        "current_address_city": "Pune",
        "current_address_district": "Pune",
        "current_address_state": "MH",
        "current_address_country": "IN",
        "current_address_pincode": "411045",
        "proof_of_address_current": "11",
        "address_in_jurisdiction_same_as_current": "Y",
        "address_in_jurisdiction_type": "",
        "address_in_jurisdiction_line1": "",
        "address_in_jurisdiction_line2": "",
        "address_in_jurisdiction_line3": "",
        "address_in_jurisdiction_city": "",
        "address_in_jurisdiction_state": "",
        "address_in_jurisdiction_country": "",
        "address_in_jurisdiction_zip": "",
        "proof_of_address_jurisdiction": "",
        "residence_telephone_std_code": "",
        "residence_telephone_number": "",
        "office_telephone_std_code": "",
        "office_telephone_number": "",
        "mobile_isd_code": "+91",
        "mobile_number": "9988770101",
        "fax_std_code": "",
        "fax_number": "",
        "email_id": "[email protected]",
        "remarks": "",
        "date_of_declaration": "13-05-2026",
        "place_of_declaration": "Pune",
        "kyc_verification_date": "13-05-2026",
        "type_of_document_submitted": "01",
        "kyc_verification_name": "Officer Sharma",
        "kyc_verification_designation": "KYC Officer",
        "kyc_verification_branch": "Pune Branch",
        "kyc_verification_emp_code": "EMP2001",
        "organisation_name": "Signzy CKYC",
        "organisation_code": "SGZ001",
        "deceased_flag": "",
        "mobile_no_2_isd_code": "",
        "mobile_no_2": "",
        "email_id_2": "",
	 "ucic": "",
        "ckyc_reference_id": "56403745410601",
        "identity_verification_flag": ""
      },
      "identityDetails": [
        {
          "record_type": "30",
          "line_number": 1,
          "identification_type": "E",
          "identity_number": "300987685658",
          "other_identity_description": "",
          "expiry_date": "",
          "identity_proof_submitted": "",
          "identity_verification_status": "02",
          "filler_1": "",
          "filler_2": "",
          "filler_3": "",
          "filler_4": ""
        }
      ],
      "relatedPersonDetails": [
        {
          "type_of_relationship": "1",
          "addition_deletion_related_person": "01",
          "kyc_number_related_person": "",
          "related_person_name_prefix": "Mr",
          "related_person_first_name": "Rajesh",
          "related_person_middle_name": "",
          "related_person_last_name": "Sharma",
          "related_person_father_spouse_name": "02",
          "related_person_father_spouse_name_prefix": "Mrs",
          "related_person_father_spouse_first_name": "Sunita",
          "related_person_father_spouse_last_name": "Sharma",
          "date_of_birth": "08-04-1943",
          "gender": "M",
          "relative_residential_status": "01",
          "differently_abled_status_flag": "0",
          "pan_form_60": "VWXPS8053V",
          "proof_of_aadhaar": "600135817149",
          "image_photograph": "<BASE64_ENCODED_IMAGE_DATA>",
          "image_POI_POA_proof": "<BASE64_ENCODED_IMAGE_DATA>",
          "image_current_address_proof": "<BASE64_ENCODED_IMAGE_DATA>",
          "proof_identity_address_line1": "45 Aundh Road",
          "proof_identity_address_line2": "Bopodi",
          "proof_identity_address_city": "Pune",
          "proof_identity_address_district": "Pune",
          "proof_identity_address_pincode": "411003",
          "proof_identity_address_state": "MH",
          "proof_identity_address_country": "IN",
          "proof_submitted_for_identity_address": "01",
          "proof_identity_address_same_as_current": "Y",
          "date_of_declaration": "13-05-2026",
          "place_of_declaration": "Pune",
          "kyc_verification_date": "13-05-2026",
          "document_submitted_type": "01",
          "kyc_verification_name": "Officer Sharma",
          "kyc_verification_designation": "KYC Officer",
          "kyc_verification_branch": "Pune Branch",
          "kyc_verification_emp_code": "EMP2501",
          "organisation_name": "Signzy CKYC",
          "organisation_code": "SGZ001"
        }
      ],
      "imageDetails": [
        {
          "image": "<BASE64_ENCODED_IMAGE_DATA>",
          "image_type": "02",
          "global_local_image_flag": "",
          "filler1": "",
          "filler2": "",
          "filler3": ""
        },
        {
          "image": "<BASE64_ENCODED_IMAGE_DATA>",
          "image_type": "04",
          "global_local_image_flag": "",
          "filler1": "",
          "filler2": "",
          "filler3": ""
        },
        {
          "image": "<BASE64_ENCODED_IMAGE_DATA>",
          "image_type": "06",
          "global_local_image_flag": "",
          "filler1": "",
          "filler2": "",
          "filler3": ""
        }
      ]
    },
  "callback_url":"
}

4.3 Response body (CKYC Create/Update)

Field	Data Type	Description
result	object	Container for the upload batch response details.
result.uploadBatchId	string	Unique ID of the upload batch.
result.recordIds	array<string>	Unique IDs of records (same order as request).
result.totalRecords	integer	Number of records accepted into the batch.

{
  "result": {
    "uploadBatchId": "56778723-1b00-4374-a148-a2d28c2b7868",
    "recordIds": [
      "5fa89fd8-b219-4fc2-8e19-627fee4e26e7",
      "71bb4dcc-84d6-4a77-bd3c-b32092565ac8"
    ],
    "totalRecords": 2
  }
}

Field	Data Type	Description
error	object	Container for error details.
error.statusCode	integer	HTTP status code returned for the request.
error.name	string	Error type or name.
error.message	string	Detailed error message describing the reason for failure.

5. Enum Code Reference (Full)

5.1 ovdType (ovdDetails.ovdType)

Code	Description
P	PAN
A	Aadhaar (last 4 digits used)
V	Voter ID
D	Driving Licence
S	Passport
N	NREGA Job Card
G	National Population Register Letter

Mirrors the identification_type codes (Refer section 5.22). Refer to CERSAI for the authoritative list when using less common values.

5.2 authFactorType (ovdDetails.authFactorType)

Code	Description	Value format
01	Date of Birth	DD-MM-YYYY
02	Aadhaar (last 4 digits)	4-digit string
03	Mobile Number	10-digit mobile (system default when not provided)

5.3 application_type (personalDetails.application_type)

Code	Description
01	New (Upload)
03	Update

5.4 Update Flags (used when application_type = "03")

Applies to: applicant_entity_name_update_flag, personal_entity_details_update_flag, address_details_update_flag, contact_details_update_flag, kyc_verification_update_flag, identity_details_update_flag, related_person_details_update_flag, image_details_update_flag.

Code	Description
01	Yes
02	No

5.5 other_details_or_deceased_information (update only)

Code	Description
01	Other Details Update
02	Deceased Information Update

5.6 constitution_type

Code	Description	Type
01	Individual	Individual
A	Sole Proprietorship	Legal Entity
B	Partnership Firm	Legal Entity
C	HUF	Legal Entity
D	Private Limited Company	Legal Entity
E	Public Limited Company	Legal Entity
F	Society	Legal Entity
G	Association of Persons (AOP) / Body of Individuals (BOI)	Legal Entity
H	Trust	Legal Entity
I	Liquidator	Legal Entity
J	Limited Liability Partnership	Legal Entity
K	Artificial Liability Partnership	Legal Entity
L	Public Sector Banks	Legal Entity
M	Central / State Government Departments / Agency	Legal Entity
N	Section 8 (Companies Act, 2013)	Legal Entity
O	Artificial Juridical Person	Legal Entity
P	International Organisation / Foreign Embassy or Consular Office	Legal Entity
Q	Not Categorized	Legal Entity
R	Others (requires constitution_type_others)	Legal Entity
S	Foreign Portfolio Investors	Legal Entity

5.7 account_type

Code	Description
01	Normal
02	Small (no longer permitted for upload)
03	Simplified (no longer permitted for upload)
04	OTP Based E-KYC
05	Minor

Update rules:

01 cannot be updated.

02 can be updated to 01, 04, and 05.

03 can be updated to 01, 04, and 05.

04 can be updated to 01 and 05.

05 can be updated to 01.

5.8 flag_father_or_spouse_name

Code	Description
01	Father Name
02	Spouse Name

5.9 gender (also relatedPersonDetails.gender)

Code	Description
M	Male
F	Female
T	Transgender

5.10 marital_status

Code	Description
01	Married
02	Unmarried
03	Others

The sample payload uses the label string ("Married") directly; the API also accepts the standard CERSAI codes above. Use codes for guaranteed acceptance.

5.11 residential_status / relative_residential_status

Code	Description
01	Resident Individual
02	Non-Resident Indian
03	Foreign National
04	Person of Indian Origin

5.12 differently_abled_status_flag

Code	Description
0	No
1	Yes

5.13 type_of_impairment (required if Refer section 5.12 = 1)

Code	Description
1	Blindness
2	Low Vision
3	Hearing Impairment
4	Locomotor Disability
5	Leprosy Cured
6	Cerebral Palsy
7	Intellectual Disability
8	Mental Illness
9	Muscular Dystrophy
10	Parkinson's Disease
11	Acid Attack Victim
12	Sickle Cell Disease
13	Hemophilia
14	Thalassemia
15	Speech and Language Disability
16	Multiple Sclerosis
17	Specific Learning Disabilities
18	Chronic Neurological Conditions
19	Autism Spectrum Disorder
20	Dwarfism

5.14 address_type (permanent / registered)

Code	Description
01	Resident / Business
02	Residential
03	Business
04	Registered Office
05	Unspecified

5.15 local_address_type (current)

Same codes as Refer section 5.14.

5.16 address_in_jurisdiction_type

Same codes as Refer section 5.14.

5.17 proof_of_address (and all POA-code fields)

Applies to: personalDetails.proof_of_address, personalDetails.proof_of_address_current, personalDetails.proof_of_address_jurisdiction, relatedPersonDetails.proof_submitted_for_identity_address, relatedPersonDetails.proof_of_address_current_address.

Individual

Code	Description	Remarks
01	Proof of Possession of Aadhaar	Last 4 digits only
02	Passport
03	Driving License
04	Voter ID
05	NREGA Job Card
08	National Population Register Letter
09	E-KYC Authentication	Last 4 digits only
10	Offline verification of Aadhaar	Last 4 digits only
11	Utility bill (≤ 2 months old)	Deemed POA — ID details & images not required
12	Property / Municipal Tax receipt	Deemed POA — ID details & images not required
13	Pension / PPO from Govt / PSU with address	Deemed POA — ID details & images not required
14	Letter of allotment from employer	Deemed POA — ID details & images not required
15	Self-Declaration	Only for current address when POI&A is Aadhaar
16	Foreign jurisdiction documents / Embassy letter	Residential status must be Foreign National

Legal Entity

Code	Description
06	Certificate of Incorporation / Formation
07	Registration Certificate
99	Others (requires proof_of_address_registered_others)

5.18 Y/N Flags

Applies to: proof_identity_address_same, address_in_jurisdiction_same_as_current, proof_identity_address_same_as_current (related person).

Code	Description
Y	Yes
N	No

5.19 type_of_document_submitted / document_submitted_type

Individual

Code	Description
01	Certified Copies
02	E-KYC data received from UIDAI
03	Data received from offline verification
04	Digital KYC process
05	Equivalent e-document
06	Video-based KYC

Legal Entity

Code	Description
01	Certified Copies
02	Equivalent e-document

5.20 state_ut — State / UT Codes (India)

Applies to: personalDetails.state_ut, personalDetails.current_address_state, personalDetails.address_in_jurisdiction_state, relatedPersonDetails.proof_identity_address_state, relatedPersonDetails.current_address_state.

Code	Description
AN	Andaman and Nicobar Islands
AP	Andhra Pradesh
AR	Arunachal Pradesh
AS	Assam
BR	Bihar
CG	Chhattisgarh
CH	Chandigarh
DD	Dadra and Nagar Haveli and Daman and Diu
DL	Delhi
GA	Goa
GJ	Gujarat
HP	Himachal Pradesh
HR	Haryana
JH	Jharkhand
JK	Jammu and Kashmir
KA	Karnataka
KL	Kerala
LA	Ladakh
LD	Lakshadweep
MH	Maharashtra
ML	Meghalaya
MN	Manipur
MP	Madhya Pradesh
MZ	Mizoram
NL	Nagaland
OD	Odisha
OR	Odisha (alternate)
PB	Punjab
PY	Puducherry
RJ	Rajasthan
SK	Sikkim
TG	Telangana
TN	Tamil Nadu
TR	Tripura
TS	Telangana (alternate)
UA	Uttarakhand
UK	Uttarakhand (new code)
UP	Uttar Pradesh
WB	West Bengal
AO	Army Post Office
XX	Other (for non-Indian addresses)

5.21 Country Codes

Applies to: personalDetails.country, personalDetails.current_address_country, personalDetails.address_in_jurisdiction_country, personalDetails.nationality, personalDetails.country_of_incorporation, personalDetails.country_of_residence_tax_laws, personalDetails.tin_issuing_country, relatedPersonDetails.nationality, relatedPersonDetails.country_of_birth, relatedPersonDetails.proof_identity_address_country, relatedPersonDetails.current_address_country.

Use ISO 3166-1 alpha-2 country codes. Common examples:

Code	Country
IN	India
US	United States
GB	United Kingdom
AE	United Arab Emirates
SG	Singapore
AU	Australia
CA	Canada
DE	Germany
FR	France
JP	Japan
CN	China
BD	Bangladesh
LK	Sri Lanka
NP	Nepal
PK	Pakistan

For the complete list, refer to the ISO 3166-1 alpha-2 standard.

5.22 identification_type (identityDetails)

Individual

Code	Description	Size	ID Required
A	Passport	20	Yes
B	Voter ID	20	Yes
D	Driving Licence	20	Yes
E	Proof of Possession of Aadhaar	12	Yes (last 4 digits)
F	NREGA Job Card	40	Yes
G	National Population Register Letter	20	Yes
H	E-KYC Authentication	12	Yes (last 4 digits)
I	Offline Verification of Aadhaar	12	Yes (last 4 digits)
J	Foreign Govt Documents / Embassy Letter	20	Optional

Legal Entity

Code	Description	Size	ID Required
C	PAN	10	Yes
01	Officially Valid Document(s) for authorised person	NA	No
02	Certificate of Incorporation / Formation	60	Yes
03	Registration Certificate	60	Yes
04	Memorandum and Articles of Association	NA	No
05	Partnership Deed	NA	No
06	Trust Deed	NA	No
07	Resolution of Board / Managing Committee	NA	No
08	Power of Attorney for transacting	NA	No
09	Activity Proof - 1	NA	No
10	Activity Proof - 2	NA	No

5.23 identity_verification_status

Code	Description
01	Yes (ID verified with issuer)
02	No (ID not verified with issuing authority)

5.24 type_of_relationship (relatedPersonDetails)

Individual

Code	Description
1	Guardian of Minor
2	Assignee
3	Authorised Representative

Legal Entity

Code	Description
4	Director
5	Promoter
6	Karta
7	Trustee
8	Partner
9	Proprietor
10	Court Appointed Official
11	Beneficiary
12	Authorised Signatory
13	Beneficial Owner
14	Power of Attorney Holder
15	Other (requires related_person_type_others_description)

5.25 addition_deletion_related_person

Code	Description
01	Addition
02	Deletion

5.26 related_person_father_spouse_name

Code	Description
01	Father Name
02	Spouse Name

5.27 image_type (imageDetails)

Individual

Code	Description	Remarks
02	Photograph	Mandatory
04	Proof of Possession of Aadhaar	Mandatory; first 8 digits must be redacted
05	Passport	One of 05/06/07 mandatory
06	Driving License	One of 05/06/07 mandatory
07	Voter ID Card	One of 05/06/07 mandatory
08	NREGA Job Card
09	Signature	Optional for all account types; not required for OTP E-KYC
35	National Population Registry Letter
36	E-KYC Authentication	First 8 digits redacted
37	Offline Verification of Aadhaar	First 8 digits redacted
42	Foreign jurisdiction documents / Embassy letter	Mandatory if POA code is 16
97	Documentary evidence for demise	For deceased updates

Legal Entity

Code	Description
09	Signature
18	Officially Valid Document(s) for authorised person
19	Certificate of Incorporation / Formation
20	Registration Certificate
21	Memorandum and Articles of Association
22	Partnership Deed
23	Trust Deed
24	Resolution of Board / Managing Committee
25	Power of Attorney for transacting
26	Activity Proof - 1 (Sole Proprietorship only)
27	Activity Proof - 2 (Sole Proprietorship only)
98	Other

5.28 global_local_image_flag

Code	Description
G	Global (shared across all records in the batch)
L	Local (specific to this record)
""	Unspecified

5.29 applicant_name_prefix (and other name prefixes)

Free text. Common values: Mr, Mrs, Ms, Dr, Shri, Smt, Kum.

5.30 identity_verification_flag (legal entity)

Code	Description
01	Done

5.31 deceased_flag (update only)

Code	Description
1	Flagged as Deceased
""	Not Deceased

6. Callback responses

After you submit records, CKYC processes each one asynchronously and POST the record's latest status to your registered callback_url every time it changes. Register the callback_url on the batch at upload; correlate callbacks to your records via

-ucic (the reference you supply per record, echoed back on every callback).

- record_id — *our* internal id for the record, stable for its entire lifetime. Returned by the upload API in the response `recordIds` array (one per record, same order as submitted), and again on every callback as `result.record_id`.

A callback fires only on a status change (deduplicated). Return 2xx within 5s; we retry up to 3 times (1s/2s/4s backoff) then drop. Branch your logic on status.

Callback payload

Request:

POST <your callback_url> · Content-Type: application/json

Headers

Header	Description
X-Status-Code	New status code — same value as result.status
X-Event-Trigger	Observability hint for what fired it (don't branch on this)
X-Delivery-Id	Unique per delivery attempt — use to de-duplicate
X-Request-Id	Same as X-Delivery-Id; also request_id in the body

Body

{
  "result": {
    "record_id": "0f1e2d3c-....",
    "status": "CKYC_GENERATED",
    "label": "CKYC number generated",
    "action_required": false,
    "ucic": "YOUR-REF-123",
    "request_id":"",
    "ckyc_number": "50098765432101"
  },
  "request_id": "a1b2c3d4-...."
}

Field	Type	Description
result.record_id	string	Our internal record id, stable for the record's lifetime
result.status	string	Machine status code — see full list below. Branch on this.
result.label	string	Human-readable label for status (safe to display)
result.action_required	boolean	true when the record is blocked awaiting a manual step
result.message	string	Present only when action_required is true — what to do
result.ucic	string \| null	Your per-record reference — key to match callback → your record
request_id	string \| null	Your per-record reference — key to match callback → your record
result.ckyc_number	string \| null	CKYC number once one exists (e.g. CKYC_GENERATED, MERGED); else null
request_id	string	Delivery id (equals X-Request-Id)

Identical payload and status set for individual and legal-entity, and for both create (new) and update — no per-type branching needed.

All possible status values

Terminal = no further change without external action.

Error = show as a bad state.

Action = who must act to advance (only these carry action_required: true + message).

Processing (pre-upload)

Status	Label	Terminal	Error	Action
QUEUED	Queued for processing	—	—	—
DEDUPE_IN_PROGRESS	Dedupe in progress	—	—	—
VALIDATION_IN_PROGRESS	Validation in progress	—	—	—
VALIDATION_FAILED	Validation failed — fix and resubmit	—	✓	Maker: fix & resubmit
REPROCESSING	Reprocessing after correction	—	—	—

Upload to CERSAI

Status	Label	Terminal	Error	Action
READY_FOR_UPLOAD	Ready for SFTP upload	—	—	—
SFTP_UPLOAD_FAILED	SFTP upload to CERSAI failed	—	✓	Ops: retry SFTP
UPLOADED_TO_CERSAI	Uploaded to CERSAI — awaiting acknowledgement	—	—	—

CERSAI acknowledgement

Status	Label	Terminal	Error	Action
CERSAI_RECEIVED_RES0_ERROR	CERSAI rejected the upload file (RES0)	—	✓	Ops: retry SFTP
CERSAI_ACK_RECEIVED	CERSAI acknowledged receipt	—	—	—
CERSAI_REJECTED_AT_INTAKE	CERSAI rejected at intake (RES1) — fix and resubmit	—	✓	Maker: fix & resubmit
CERSAI_ACCEPTED_AWAITING_PERIODIC	CERSAI accepted — awaiting periodic outcome	—	—	—
CERSAI_REJECTED_PERIODIC	CERSAI rejected (periodic) — fix and resubmit	—	✓	Maker: fix & resubmit
ID_NOT_CONFIRMED	Identity not confirmed by CERSAI — review data	—	✓	Maker: fix & resubmit
CKYC_GENERATED	CKYC number generated	✓	—	— (success)

Reconciliation (probable duplicate)

Status	Label	Terminal	Error	Action
PROBABLE_MATCH_PENDING_DECISION	Probable match found — awaiting maker decision	—	—	Maker: review recon
AUTO_NO_MATCH_AWAITING_FILE	Auto-decided No-Match — decision file not yet generated	—	—	Ops: review auto-NM
DECISION_SUBMITTED	Decision submitted to CERSAI	—	—	—
RECON_COMPLETED_NO_MATCH	Recon completed — No Match	✓	—	—

Deactivation & merge

Status	Label	Terminal	Error	Action
DEACTIVATION_QUEUED	Deactivation queued for next batch flush	—	—	—
DEACTIVATION_SUBMITTED	Deactivation submitted to CERSAI	—	—	—
DEACTIVATION_REJECTED	Deactivation rejected by CERSAI — retry required	—	✓	Maker: retry deactivation
DEACTIVATION_ACK_AWAITING_MERGE	CERSAI acknowledged deactivation — awaiting merge	—	—	—
MERGED	CKYC records merged	✓	—	— (success)

ReKYC

Status	Label	Terminal	Error	Action
REKYC_AWAITING_CUSTOMER	ReKYC email sent — awaiting customer choice	—	—	Customer: choose
REKYC_CUSTOMER_CHOSE_CERSAI	Customer chose CERSAI revalidation	✓	—	—
REKYC_CUSTOMER_CHOSE_BANK	Customer chose bank revalidation	—	—	—
REKYC_CUSTOMER_CHOSE_NONE	Customer declined	✓	—	—
REKYC_AUTO_HANDLED	Handled automatically (no customer action)	✓	—	—
REKYC_ERROR	ReKYC failed	✓	✓	Maker: fix & resubmit

Fallback

Status	Label	Terminal	Error	Action
UNKNOWN	Status unknown	—	—	—

Minimum you must handle: CKYC_GENERATED / MERGED (success — store ckyc_number), any row with an Action (blocked — surface to the actor), and everything else as informational progress. New status codes may be added over time (never renamed) — treat unrecognized codes as informational progress.

7. Conventions and Rules

Topic	Rule
Date format	All dates use DD-MM-YYYY (e.g., 20-03-1988).
Aadhaar masking (text)	For Aadhaar-based identity types (E, H, I), supply only the last 4 digits in identity_number.
Aadhaar masking (images)	For image types 04, 36, 37 (Aadhaar-related), the first 8 digits must be redacted in the uploaded image bytes.
Image encoding	Each image field contains raw base64 (no data:image/...;base64, prefix).
Mandatory images per record	At least 3 image objects: 02 (Photograph), 04 (Aadhaar POI), and one of 05/06/07 (Passport / DL / Voter ID).
OTP E-KYC	When account_type = "04", identification_type must be H and image type 09 (Signature) is not required.
Updates (application_type = "03")	Set the relevant *_update_flag fields to 01 (Yes); leave others as "" or 02 (No).
Empty optional fields	Send empty strings ("") rather than null, except where the schema explicitly permits null (e.g., ovdDetails.ckycNumber).
Batch uniqueness	ckyc_no_or_fi_reference_no must be unique across all records within a single batch.
Deemed POA	For POA codes 11–14, identity-detail entries and POI/POA images are not required.
Foreign jurisdiction	For Foreign Nationals (residential_status = 03) using POA 16, image type 42 is mandatory.

CKYC Create and Update API

Introduction

API Details

Authentication Overview

Login API

CKYC Upload/Update API

Header

Request Body

4.2 Request body

4.3 Response body (CKYC Create/Update)

5. Enum Code Reference (Full)

5.1 ovdType (ovdDetails.ovdType)

5.2 authFactorType (ovdDetails.authFactorType)

5.3 application_type (personalDetails.application_type)

5.4 Update Flags (used when application_type = "03")

5.5 other_details_or_deceased_information (update only)

5.6 constitution_type

5.7 account_type

5.8 flag_father_or_spouse_name

5.9 gender (also relatedPersonDetails.gender)

5.10 marital_status

5.11 residential_status / relative_residential_status

5.12 differently_abled_status_flag

5.13 type_of_impairment (required if Refer section 5.12 = 1)

5.14 address_type (permanent / registered)

5.15 local_address_type (current)

5.16 address_in_jurisdiction_type

5.17 proof_of_address (and all POA-code fields)

5.18 Y/N Flags

5.19 type_of_document_submitted / document_submitted_type

5.20 state_ut — State / UT Codes (India)

5.21 Country Codes

5.22 identification_type (identityDetails)

5.23 identity_verification_status

5.24 type_of_relationship (relatedPersonDetails)

5.25 addition_deletion_related_person

5.26 related_person_father_spouse_name

5.27 image_type (imageDetails)

5.28 global_local_image_flag

5.29 applicant_name_prefix (and other name prefixes)

5.30 identity_verification_flag (legal entity)

5.31 deceased_flag (update only)

6. Callback responses

Callback payload

All possible status values

Processing (pre-upload)

Upload to CERSAI

CERSAI acknowledgement

Reconciliation (probable duplicate)

Deactivation & merge

ReKYC

Fallback

7. Conventions and Rules

﻿