Enhancement of Validations in Unique Client Code Fields

[Image omitted. See the official document.]

Technical Design Document

UCI External interface

© Copyright, NSE

---

Contents

Purpose............................................................................................................................................. 4
Scope ................................................................................................................................................ 4
Target Audience................................................................................................................................ 4
Messaging Protocols......................................................................................................................... 5
Authorization.................................................................................................................................... 5
One-Time API User Registration........................................................................................................ 6
User Registration URL ....................................................................................................................... 6
https://uat.connect2nsccl.com/api-reg/welcome.............................................................................. 6
User Registration .............................................................................................................................. 6
API Endpoints ................................................................................................................................. 10

1. Authentication API.................................................................................................................. 10

• • API Description.................................................................................................................... 10
• • End-Point URL...................................................................................................................... 10
• • Request Method.................................................................................................................. 10
• • Sample Request Payload ..................................................................................................... 10
• • Sample Response Payload................................................................................................... 10

2. Upload/ Process Client API...................................................................................................... 11

• • API Description.................................................................................................................... 11
• • End-Point URL...................................................................................................................... 11
• • Request Method.................................................................................................................. 11
• • Threshold Limit.................................................................................................................... 11
• • Request Details ................................................................................................................... 11
• • Request Payload Sample ..................................................................................................... 58
• • Response Details................................................................................................................. 61
• • Response Payload Sample ................................................................................................... 61
• • Expected Response code and Messages.............................................................................. 62

3. Get PAN Status API.................................................................................................................. 63

• • API Description.................................................................................................................... 63
• • End-Point URL...................................................................................................................... 63
• • Request Method.................................................................................................................. 63
• • Request Details ................................................................................................................... 63
• • Response Details................................................................................................................. 64
• • Sample Request Payload ..................................................................................................... 65
• • Sample Response Payload ................................................................................................... 65
• • Expected Response code and Messages.............................................................................. 66

4. Get UCC-Wise PAN Status API ................................................................................................. 67

• • API Description.................................................................................................................... 67
• • End-Point URL...................................................................................................................... 67
• • Request Method.................................................................................................................. 67
• • Threshold Limit.................................................................................................................... 67
• • Request Details ................................................................................................................... 67
• • Response Details................................................................................................................. 67
• • Sample Request Payload ..................................................................................................... 68
• • Sample Response Payload ................................................................................................... 69
• • Expected Response code and Messages.............................................................................. 70
  Annexure ........................................................................................................................................ 71

1. Client Category List.............................................................................................................. 71
2. State List.............................................................................................................................. 72
3. Country List ......................................................................................................................... 73
4. Alpha Relationship .............................................................................................................. 80

---

Purpose

This document describes the protocol for Web API based real time communication between NSE and its Trading Members. The document serves as a common guide for developing and testing interfaces between systems at Exchange and its Members.

Scope

Bidirectional external interface API’s will be provided as REST endpoints accessible over internet using HTTPS protocol. All messages in the online API’s will be in JSON format.

Target Audience

All trading members wants to send their client information to NSE would consume the exchange end-point.

---

Messaging Protocols

• • Messages or all request and response messages are in JSON (JavaScript Object Notation) format.
• • Following headers need to be provided in all API calls
• a. Content-Type: Header value should be “application/json”
• • A value could be Boolean (true/false), number, decimal, String or a structure (List or Object).
• • All dates, times and date times are represented in Indian standard time.
• • For date fields, format will be varied from API to API and the details will be provided on respective API.

Authorization

• • The API consumer application is expected to send following headers (case-sensitive) in every API HTTPS request.
• o Token: A unique identifier generated for all successful login.
• • The API provider is not required to provide any header in its response.
• • Token will have expiry of 30 minutes.

JWT mechanism is used to generate API authentication tokens as it is widely used industry standard. (Implemented by NSE)

---

One-Time API User Registration

User Registration URL

https://lama.uat.nseindia.com/api-reg/welcome

User Registration

• • Use the above one-time user registration link and complete the simple registration process by providing valid ‘membercode’, 'password’ and ‘emailId’ in below and its subsequent page.

[Image omitted. See the official document.]

• • User/Member will receive an OTP on the given email id by clicking the ‘SEND OTP’ button. Use the OTP to complete the process. This ‘member code’ and ‘password’ will be used during API JWT authentication process.

[Image omitted. See the official document.]

---

• • On successful registration, user will see a message – “XXXXX registered successfully! Please contact UCI Admin for activation.” Member need to intimate Exchange for Activation on Email ID- uci@nse.co.in

[Image omitted. See the official document.]

• • Follow similar process for resetting the password.
• • To reset password, enter the member code and click on RESET PASSWORD button.

[Image omitted. See the official document.]

• • Enter new password, confirm the new password and then click on SEND OTP button to receive the OTP on the registered mail ID as shown in the below image.

---

[Image omitted. See the official document.]

• • Enter OTP and click on the SAVE button as shown in the below image.

[Image omitted. See the official document.]

• • You will be redirected to the welcome page with the message as shown in the below image.

[Image omitted. See the official document.]

---

API Endpoints

1. Authentication API

• • API Description
  This API is used to authenticate the user and provide a shot life authentication token to use the subsequent API.

• • End-Point URL
  https://clientprofilinguat.nseindia.com/uciservice/api/auth

Provide request body while calling this API as mentioned in the same request. The details should be same as the one-time user registration ‘membercode’ and ‘password’. ‘apiName’ should be ‘uci_clientupload’.

• • Request Method
  POST

• • Sample Request Payload

{
"username": "member14",
"password": "Abcd@123",
"apiName": "uci_clientupload"
}

• • Sample Response Payload

{
"token":
"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJtZW1iZXIxNCIsImV4cCI6MTU4MjAwODg0MSwiaWF0Ij
oxNTgyMDA1MjQxfQ.PIcIJ6R-TOCJN71rR_UEsL12DU6ngu2gpWkKnCbQt6ciAzCoftMI4iWZvY15K2GM405DC0N71O6Opn5f8Med
eg"
}

---

2. Upload/ Process Client API

• • API Description
  This API is used to create a client information in the UCI system. It validates the client information provided before persisting to the system. The validation includes basic field level value against its data type and standard UCC business logic validations. If the validation fails, then the respective validation message is returned to the end user.

• • End-Point URL

API-2-Client Upload

https://clientprofilinguat.nseindia.com/uciservice/api/clientupload

• • Request Method

POST

• • Threshold Limit

Initially API is limited to handle only 50 clients per request.

• • Request Details

Provide the First API response in the Authorization header while calling the second API with the request body. Sample header details are as below.

[Image omitted. See the official document.]

Note: Strictly adhere to the following field level validation for smooth and high-performance throughput.

All fields in the request are repeated for each client. All dates are in DD-MM-YYYY format.

Where TM is doing proprietary trading, the account type shall be "OWN" and Values are: OWN ERROR CLIENT

Where Account type is selected as “OWN”, PAN should be of member.

Where Account Type is selected as “ERROR”, PAN should be of member and client code should be “ERROR “ or “ERROR%” where % is a number.

For all other entites, the client type shall be "Client".

Example TM Code | UCC | PAN| Client Type 12345| 12345| abcde1234f | OWN 12345 | ERROR | abcde1234f | Error 12345 | 1231 | abcde1234f | OWN 12345 | 1234560 | xyzav1234d | Client 12345 | 68952000 | amnsd1234a | Client | | 3 | Opt for UPI | ccdOptForUpi | String Min – 1 Max – 2 | M | For applicable categories 'Individual and HUF' (1 & 3) the value can be "Y" or "N".

For Individual and HUF category where custodian details have been provided then value shall be "NA".

For categories other than applicable categories the value shall be "NA".

This facility shall not be applicable for "PAN_Exempt" cases and the value shall be "NA".

Registered - Y Not opted - N Not applicable - NA Deregistered - D