Unified KYC - Basic Check

Overview & Purpose

The Global Unified KYC API is a single identity verification endpoint designed to simplify customer onboarding and identity verification across multiple countries. Instead of integrating separate APIs for each geography, businesses can leverage three standardized endpoint, one authentication mechanism, and one request schema to perform KYC verification globally.

The API abstracts country-specific complexities by providing a unified input and output structure while internally routing requests to the appropriate country-specific verification source. This significantly reduces integration effort, accelerates go-to-market timelines, and enables seamless expansion into new geographies without requiring additional development work.

Coverage: Brazil, Peru, Colombia, Indonesia, Mexico, Argentina, South Africa, Chile, Bolivia, China, Kenya, Nigeria, Qatar, Kuwait

Key Features and Functionalities of this API Include:

Global Identity Verification – Verify customer identities across multiple countries through a single unified API endpoint.

Unified Request & Response Schema – Use a standardized input and output format across all countries, simplifying implementation and maintenance.

Standardized Verification Results – Receive consistent verification responses regardless of the country, with additional country-specific attributes returned in a dedicated metadata object.

Scalable Global Coverage – Expand to new countries without modifying your existing integration simply specify the desired country in the request.

Fraud Prevention & Identity Protection – Help reduce identity fraud by validating customer information against trusted and authoritative data sources.

Improved Customer Onboarding – Deliver a seamless and consistent KYC verification experience across multiple geographies through a single integration.

Sample cURL

Pre-Production

Production

curl --location 'https://api-preproduction.signzy.app/api/v3/global-kyc/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: *****' \
--data '{
    "countryCode": "BR",
    "docType": "National ID",
    "firstName": "Joao",
    "middleName": "",
    "lastName": "Silva",
    "dateOfBirth": "1990-01-15",
    "gender": "Male",
    "addressLine1": "Rua das Flores 123",
    "addressLine2": "Bairro Jardins",
    "addressLine3": "Sao Paulo",
    "addressLine4": "SP",
    "addressLine5": "****",
    "identityInformation": {
        "nationalIdNumber": "****"
    },
    "consent": true
}'

curl --location 'https://api.signzy.app/api/v3/global-kyc/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: *****' \
--data '{
    "countryCode": "BR",
    "docType": "National ID",
    "firstName": "Joao",
    "middleName": "",
    "lastName": "Silva",
    "dateOfBirth": "1990-01-15",
    "gender": "Male",
    "addressLine1": "Rua das Flores 123",
    "addressLine2": "Bairro Jardins",
    "addressLine3": "Sao Paulo",
    "addressLine4": "SP",
    "addressLine5": "****",
    "identityInformation": {
        "nationalIdNumber": "****"
    },
    "consent": true
}'

API Input

The API expects the following input in the request payload:

{
    "countryCode": "BR",
    "docType": "National ID",
    "firstName": "Joao",
    "middleName": "",
    "lastName": "Silva",
    "dateOfBirth": "1990-01-15",
    "gender": "Male",
    "addressLine1": "Rua das Flores 123",
    "addressLine2": "Bairro Jardins",
    "addressLine3": "Sao Paulo",
    "addressLine4": "SP",
    "addressLine5": "****",
    "identityInformation": {
        "nationalIdNumber": "****"
    },
    "consent": true
}

Field	Type	Required	Validation / Notes
countryCode	string	Yes (all)	2-letter ISO country code, case-insensitive (normalized to uppercase).
docType	string	Yes (all)	Must be a supported document type for the specified country.
consent	boolean	Yes (all)	Must be the boolean value true. String values like "true", false, or a missing field are rejected.
firstName	string	Country-dependent	Letters, spaces, and . only. Maximum 70 characters.
middleName	string	Optional (most countries)	Letters, spaces, and . only. Maximum 70 characters.
lastName	string	Country-dependent	Letters, spaces, and . only. Maximum 70 characters.
fullName	string	Country-dependent	Used when the full name is provided as a single field (e.g., South Africa, China). Maximum 70 characters. For China, only Chinese characters are allowed.
dateOfBirth	string	Country-dependent	Format: YYYY-MM-DD. Must be a valid calendar date, year ≥ 1901, and not a future date.
gender	string	Optional	Allowed values: Male or Female.
addressLine1	string	Country-dependent	Maximum 100 characters. Must contain at least one letter or digit.
addressLine2	string	Country-dependent	Maximum 100 characters. Must contain at least one letter or digit.
addressLine3	string	Country-dependent	Maximum 100 characters. Must contain at least one letter or digit.
addressLine4	string	Country-dependent	Maximum 100 characters. Must contain at least one letter or digit.
addressLine5	string	Country-dependent	Maximum 100 characters. Often represents the postal code and must follow country-specific format requirements.
identityInformation	object	Country-dependent	Container for nationalIdNumber and other country-specific identity fields.
identityInformation.nationalIdNumber	string	Country-dependent	Must follow the country-specific national ID format.
identityInformation.issueDate	string	Colombia (CO) only	Required for Colombia. Format: YYYY-MM-DD.
countrySpecificFields	object	Mexico (MX) only	Contains country-specific fields such as fatherLastName and motherLastName.

Country specific input validations

Country	Code	Doc Type	ID / Key Format	Required Identity Fields
Nigeria	NG	NIN	11 digits	firstName, lastName, dateOfBirth, nationalIdNumber
Nigeria	NG	BVN	11 digits	firstName, lastName, dateOfBirth, nationalIdNumber
Kenya	KE	National ID	7 or 8 digits	firstName, lastName, dateOfBirth, nationalIdNumber
South Africa	ZA	National ID	13 digits	fullName, dateOfBirth, nationalIdNumber
Mexico	MX	CURP	18 alphanumeric	firstName, fatherLastName, motherLastName, dateOfBirth, nationalIdNumber
China	CN	Resident ID	18 digits	fullName (Chinese only), dateOfBirth, nationalIdNumber
Indonesia	ID	NIK	16 digits, not starting with 0	firstName, dateOfBirth, nationalIdNumber
Indonesia	ID	National ID	16 digits	firstName, lastName, dateOfBirth, nationalIdNumber
Kuwait	KW	Civil Card	12 digits	nationalIdNumber
Chile	CL	RUN	8–9 alphanumeric	nationalIdNumber
Bolivia	BO	National ID	5–10 alphanumeric	dateOfBirth, nationalIdNumber
Colombia	CO	National ID	6–10 digits	nationalIdNumber, issueDate
Peru	PE	National ID	Exactly 8 digits	nationalIdNumber
Argentina	AR	DNI	8 digits	firstName, lastName, dateOfBirth, nationalIdNumber

API Output

{
  "result": {
    "countryCode": "KE",
    "docType": "National ID",
    "nameMatchScore": "1.00",
    "addressMatchScore": "",
    "verificationStatus": "Verified",
    "verificationResult": {
      "firstName": "true",
      "middleName": "",
      "lastName": "true",
      "fullName": "",
      "dateOfBirth": "true",
      "gender": "",
      "addressLine1": "",
      "addressLine2": "",
      "addressLine3": "",
      "addressLine4": "",
      "addressLine5": "",
      "nationalIdNumber": "true",
      "phoneNumber": "",
      "landlineNo": "",
      "emailAddress": ""
    }
  },
  "reason": "Request Successful",
  "code": "S001"
}

Response Parameters

Field	Type	Description	Values / Example
result	object	Container for the verification outcome. Returns {} for S003 and error responses.	{ ... }
reason	string	Human-readable status message.	"Request Successful"
code	string	Machine-readable status code. S001 indicates success.	"S001"
result.countryCode	string	Normalized (uppercase) country code.	"KE"
result.docType	string	Requested document type.	"National ID"
result.nameMatchScore	string	Ratio of matched name fields (2 decimal places). Empty if no name fields apply.	"0.00"–"1.00" or ""
result.addressMatchScore	string	Ratio of matched address fields (2 decimal places). Empty if no address fields apply.	"0.00"–"1.00" or ""
result.verificationStatus	string	Overall verification outcome derived from verificationResult.	Verified, Partially Verified, Not Verified, Unable to Verify
result.verificationResult	object	Contains per-field verification results. Every key is always present. Values are "true", "false", or "" if not returned by the vendor.	{ ... }
result.verificationResult.firstName	string	First name match result.	"true" / "false" / ""
result.verificationResult.middleName	string	Middle name match result.	"true" / "false" / ""
result.verificationResult.lastName	string	Last name match result.	"true" / "false" / ""
result.verificationResult.fullName	string	Full name match result (used where name is a single field, e.g., ZA, CN).	"true" / "false" / ""
result.verificationResult.dateOfBirth	string	Date of birth match result.	"true" / "false" / ""
result.verificationResult.gender	string	Gender match result.	"true" / "false" / ""
result.verificationResult.addressLine1	string	Address Line 1 match result.	"true" / "false" / ""
result.verificationResult.addressLine2	string	Address Line 2 match result.	"true" / "false" / ""
result.verificationResult.addressLine3	string	Address Line 3 match result.	"true" / "false" / ""
result.verificationResult.addressLine4	string	Address Line 4 match result.	"true" / "false" / ""
result.verificationResult.addressLine5	string	Address Line 5 (postal code) match result.	"true" / "false" / ""
result.verificationResult.nationalIdNumber	string	National ID match result.	"true" / "false" / ""
result.verificationResult.phoneNumber	string	Phone number match result.	"true" / "false" / ""
result.verificationResult.landlineNo	string	Landline number match result.	"true" / "false" / ""
result.verificationResult.emailAddress	string	Email address match result.	"true" / "false" / ""
Verification Status Derivation	—	Calculated over non-empty fields in verificationResult.	Verified: all "true"; Partially Verified: some "true"; Not Verified: no "true" but at least one non-empty field; Unable to Verify: all fields empty.

Success Codes

HTTP Status Code	Success Code	Description
200	S001	Request Successful.
200	S003	Data not Found on source.

Sample Error

{
  "result": {},
  "reason": "Invalid nationalIdNumber. Must be 7 or 8 digits.",
  "code": "E001"
}

Error Response Parameters

Parameter	Description
result	Empty result object
reason	Reason for error
status	Status of the api
code	Error code from Signzy

Error Codes

HTTP Status Code	Error Code	Description
400	E001	Bad Request
401	E101	Unauthorized Access
403	E201	Forbidden
404	E301	Data Not Found
409	E401	Upstream error
429	E501	Rate Limit Exceeded
500	E601	Internal Server Error
503	E701	Service Unavailable
504	E801	Timeout

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.

We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!