LEI Validation

Endpoint Overview

POST /api/v1/lei-validation/

Description

The LEI Validation API allows you to validate and retrieve comprehensive information about a Legal Entity Identifier (LEI). An LEI is a 20-character alphanumeric code that uniquely identifies legal entities participating in financial transactions globally. This API helps verify the authenticity of an LEI code and returns detailed information about the associated entity, including its legal name, addresses, registration details, and current status.

Key Benefits

Instant verification of LEI codes against official records

Access to comprehensive entity information including legal addresses and registration details

Simplified compliance with KYC and AML regulations

Reduced manual verification efforts and associated costs

Use Cases

Financial Services

Compliance & Risk

Corporate Services

Verify counterparty LEIs before executing financial transactions

Streamline client onboarding by automating LEI validation

Maintain regulatory compliance with financial reporting requirements

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 for authentication (JWT format)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
lei_code	String	Yes	Legal Entity Identifier Number to be validated

Example Request

{
    "lei_code": "12345678987"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all the entity information
data.client_id	String	Unique Client ID generated by the system
data.lei_number	String	LEI Number (null if not found)
data.full_name	String	Entity's full legal name
data.legal_entity_address	Object	Entity's registered address details
data.headquarters_entity_address	Object	Entity's headquarters address details
data.entity_identifiers	Object	Entity's registration and identification details
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the response message

Legal Entity Address Object

Parameter	Type	Description
registered_first_address_line	String	Full address of legal entity
additional_address_line_1	String	Additional address details
additional_address_line_2	String	Additional address details
additional_address_line_3	String	Additional address details
country	String	Entity country name
region	String	Entity region name
city	String	Entity city name
zipcode	String	Postal/ZIP code

Headquarters Entity Address Object

Parameter	Type	Description
registered_first_address_line	String	Full address of headquarters
additional_address_line_1	String	Additional address details
additional_address_line_2	String	Additional address details
additional_address_line_3	String	Additional address details
country	String	Headquarters country name
region	String	Headquarters region name
city	String	Headquarters city name
zipcode	String	Postal/ZIP code

Entity Identifiers Object

Parameter	Type	Description
registration_authority_name	String	Name of the registration authority
registration_authority_id	String	ID assigned by the registration authority
jurisdiction	String	Legal jurisdiction code
legal_form	String	Entity legal form description
lei_registration_date	String	Initial LEI registration date (YYYY-MM-DD)
lei_registration_last_update	String	Last update date of LEI (YYYY-MM-DD)
entity_status	String	Current status of the entity (e.g., ACTIVE)
entity_expiration_date	String	Entity expiry date if applicable (YYYY-MM-DD)
lei_next_renewal_date	String	Next LEI renewal date (YYYY-MM-DD)
entity_expiration_reason	String	Reason for expiration if applicable
lei_registration_status	String	Current LEI registration status
succsessor_lei	String	Successor LEI if entity has merged or changed
lou_id	String	Local Operating Unit ID
lei_validation_source	String	Source used for LEI validation

Example Successful Response

{
    "data": {
        "client_id": "lei_HcgafcYhJlqFsExmmwjA",
        "lei_number": null,
        "full_name": "ENERGY PVT LTD",
        "legal_entity_address": {
            "registered_first_address_line": "NAYAPALLI BHUBANESWAR",
            "additional_address_line_1": "",
            "additional_address_line_2": "",
            "additional_address_line_3": "",
            "country": "India",
            "region": "Odisha",
            "city": "XXXXX",
            "zipcode": "XXXXXX"
        },
        "headquarters_entity_address": {
            "registered_first_address_line": "NAYAPALLI BHUBANESWAR",
            "additional_address_line_1": "",
            "additional_address_line_2": "",
            "additional_address_line_3": "",
            "country": "India",
            "region": "Odisha",
            "city": "XXXXX",
            "zipcode": "XXXXXX"
        },
        "entity_identifiers": {
            "registration_authority_name": "Ministry of Corporate Affairs",
            "registration_authority_id": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
            "jurisdiction": "IN",
            "legal_form": "Private Limited Companies",
            "lei_registration_date": "0000-06-11",
            "lei_registration_last_update": "0000-06-12",
            "entity_status": "ACTIVE",
            "entity_expiration_date": "",
            "lei_next_renewal_date": "0000-06-11",
            "entity_expiration_reason": "",
            "lei_registration_status": "LAPSED",
            "succsessor_lei": "",
            "lou_id": "LEIL",
            "lei_validation_source": "XXXXXXXXXX"
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid LEI Code

LEI Not Found

Authentication Error

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid LEI code format",
    "message_code": "invalid_lei_format"
}

The provided LEI code does not match the required format. LEI codes should be 20-character alphanumeric strings.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

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

Rotate authentication tokens periodically according to your security policy

User Experience Guidelines

Implement client-side validation of LEI format before making API calls

Display meaningful error messages to users when validation fails

Cache validated LEI data when appropriate to improve performance

Provide clear visual indicators when validation is in progress and when it completes

Code Samples

cURL

Python

Node.js

Related APIs

Entity Verification API: Verify company details against official registries

Document Verification API: Validate identity documents for KYC processes

Address Verification API: Verify and standardize physical addresses

PAN Verification API: Validate Permanent Account Numbers for Indian entities

Compliance and Legal Considerations

LEI data is subject to data protection regulations in various jurisdictions. Ensure you have appropriate consent before storing or processing LEI information. The Global Legal Entity Identifier Foundation (GLEIF) maintains standards for LEI usage. This API helps with compliance requirements related to financial regulations such as MiFID II, EMIR, and Dodd-Frank, which mandate LEI usage for certain transactions.

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/lei-validation/' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "lei_code": "12345678987" }'

{ "data": { "client_id": "lei_HcgafcYhJlqFsExmmwjA", "lei_number": null, "full_name": "ENERGY PVT LTD", "legal_entity_address": { "registered_first_address_line": "NAYAPALLI BHUBANESWAR", "additional_address_line_1": "", "additional_address_line_2": "", "additional_address_line_3": "", "country": "India", "region": "Odisha", "city": "XXXXX", "zipcode": "XXXXXX" }, "headquarters_entity_address": { "registered_first_address_line":"NAYAPALLI BHUBANESWAR", "additional_address_line_1": "", "additional_address_line_2": "", "additional_address_line_3": "", "country": "India", "region": "Odisha", "city": "XXXXX", "zipcode": "XXXXXX" }, "entity_identifiers": { "registration_authority_name": "Ministry of Corporate Affairs", "registration_authority_id": "XXXXXXXXXXXXXXXXXXXXXXXXXX", "jurisdiction": "IN", "legal_form": "Private Limited Companies", "lei_registration_date": "0000-06-11", "lei_registration_last_update": "0000-06-12", "entity_status": "ACTIVE", "entity_expiration_date": "", "lei_next_renewal_date": "0000-06-11", "entity_expiration_reason": "", "lei_registration_status": "LAPSED", "succsessor_lei": "", "lou_id": "LEIL", "lei_validation_source": "XXXXXXXXXX" } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

LEI Validation

LEI Validation#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Legal Entity Address Object#

Headquarters Entity Address Object#

Entity Identifiers Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

LEI Validation

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Legal Entity Address Object

Headquarters Entity Address Object

Entity Identifiers Object

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples