• Select

  • Select

Create Account Holder

Create Account Holder
Published on 20th August, 2021

An account holder refers to a real/legal customer to Fusion. Drawing from the real world analogy, an account holder can be an actual person who holds an account at a bank or can be a legal entity like a corporate entity, or merchant. This article lays down the steps fintech shall follow to create an account holder with fusion. Before you begin, it is advised that you familiarize yourself with key Account Holder concepts explained in About Account Holders.

Account Holder Profile Ownership

The Account Holder on-boarded on Fusion has a banking relationship with the Issuer (IFI) that the fintech has partnered with. Therefore, the Issuer determines which details of the Account Holder are accessible by the fintech.

Pre-requisite Information for Account Holder

When an Account Holder is on-boarded on Fusion, typically the below details are required–

  • Personal information, like Full Name, contact information
  • Officially Valid Document (OVD), like Aadhaar number, PAN card, Voter’s ID card, etc.

If you need to collect additional information, Fusion provides custom attributes for this purpose. For example, you can store an Account Holder’s additional mobile number or Unique Customer Identification Code (UCIC) against the application.

Creating Application for Account Holder creation

In order to create a new account holder, first, an Application shall be created for the same on Fusion. The issuer will then review the Application. Once approved by the issuer, the account holder is created with a unique identifier (accountHolderID , individualID). Fintech can then issue the ‘Bundle’ to this account holder.

Note: An applicant may sign up with multiple Fintechs under the same issuer. Zeta system maintains a single identity of an Account Holder per issuer. This is in line with the compliance requirements of the bank and the regulator. This means that if an applicant signs up with multiple fintech’s working with Fusion on the same issuer, there would only be one Account Holder entity.

The fintechs can create an application for the account holder creation using either of the below endpoints.

  • POST /api/v1/ifi/{{ifiID}}/spool/{{spoolid}}/application
  • POST /api/v1/ifi/{ifiID}/applications/newIndividual

The Account Holder’s personal, contact and KYC information shall be then, provided in the request body. Here, Fusion will check for an already existing account holder on the contact number with the IFI.

Note: The /newIndividual API is going to be deprecated soon. Fusion will be using the Applications APIs to create account holders.

Endpoint URI: /application

POST/api/v1/ifi/{{ifiID}}/spool/{{spoolid}}/application
cURL Sample
Switch Theme
Expand More
Copy 
curl --location --request POST '{{fusion_base_url}}/api/v1/ifi/{{ifiID}}/spool/{{spoolid}}/application' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{token}} \
--data-raw '{
    "requestId": "request_cah-233",
    "vectors": [{
        "type": "e",
        "value": "[email protected]"
    }],
    "sections": {"AccountHolderDetails" : {
        "name": "AccountHolderDetails",
        "type": "CreateRealAccountHolder",
        "details": {
            "individualType": "REAL",
            "dob": {
                "year": 1957,
                "dayOfMonth": 13,
                "month": 7
            },
            "salutation": "Mr.",
            "firstName": "Sarthak",
            "lastName": "Verma",
            "middleName": "Kumar",
            "profilePicURL": "https://s3.amazonaws.com/uifaces/faces/twitter/darylws/128.jpg",
            "applicationType": "CREATE_ACCOUNT_HOLDER",
            "gender": "MALE",
            "mothersMaidenName": "xyz"
        }
    }
    }
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy 
{
    "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
    "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
    "ifiId": 140793,
    "requestId": "request_cah-233",
    "status": "DATA_CAPTURE_INITIATED",
    "sections": {
        "AccountHolderDetails": {
            "sectionId": "4d62f76d-9826-4b72-a7f5-c3c885e2f6b9",
            "ifiId": 140793,
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "name": "AccountHolderDetails",
            "type": "CreateRealAccountHolder",
            "details": {
                "dob": {
                    "year": 1957.0,
                    "month": 7.0,
                    "dayOfMonth": 13.0
                },
                "gender": "MALE",
                "lastName": "Verma",
                "firstName": "Sarthak",
                "middleName": "Kumar",
                "salutation": "Mr.",
                "profilePicURL": "https://s3.amazonaws.com/uifaces/faces/twitter/darylws/128.jpg",
                "individualType": "REAL",
                "applicationType": "CREATE_ACCOUNT_HOLDER",
                "mothersMaidenName": "xyz"
            },
            "createdAt": "2021-02-19T10:40:04.837+05:30",
            "updatedAt": "2021-02-19T10:40:04.837+05:30"
        }
    },
    "vectors": [
        {
            "vectorId": "d8979db7-bc16-4934-9450-4c33a3991791",
            "ifiId": 140793,
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "type": "e",
            "value": "[email protected]",
            "status": "ENABLED",
            "attributes": {},
            "createdAt": "2021-02-19T10:40:04.707+05:30",
            "updatedAt": "2021-02-19T10:40:04.707+05:30"
        }
    ],
    "stages": [
        {
            "stageId": "2b7c5ecc-64dc-4985-93d8-b1dfb8788de5",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "ASSESSMENT",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.036+05:30",
            "updatedAt": "2021-02-19T10:40:05.036+05:30"
        },
        {
            "stageId": "24691789-c586-49fc-9071-ef5c58066211",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "DATA_CAPTURE",
            "status": "INITIATED",
            "details": {},
            "result": {
                "validationFailed": [
                    {
                        "code": "APPLICATION_SCHEMA_VALIDATION_FAILED",
                        "type": "JsonSchemaValidator",
                        "status": "FAILED",
                        "message": "#: #: only 1 subschema matches out of 2",
                        "attributes": {
                            "errorMessages": [
                                "#/sections: required key [Personal] not found",
                                "#/sections: required key [Vectors] not found"
                            ]
                        }
                    }
                ]
            },
            "createdAt": "2021-02-19T10:40:05.024+05:30",
            "updatedAt": "2021-02-19T10:42:20.436+05:30"
        },
        {
            "stageId": "3546099b-4d81-42d5-abea-05dfbadf50a2",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "ENRICHMENT",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.036+05:30",
            "updatedAt": "2021-02-19T10:40:05.036+05:30"
        },
        {
            "stageId": "11f04481-6e07-4036-b549-69a1868abdfc",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "PROVISIONING",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.036+05:30",
            "updatedAt": "2021-02-19T10:40:05.036+05:30"
        },
        {
            "stageId": "e6163594-0b26-4d96-a890-79231c7adcf4",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "REVIEW",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.037+05:30",
            "updatedAt": "2021-02-19T10:40:05.037+05:30"
        }
    ],
    "tags": [
        {
            "type": "spool-id",
            "value": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "attributes": {}
        },
        {
            "type": "vbo-id",
            "value": "26c28ca6-4202-464c-9806-b788989762d4",
            "attributes": {}
        }
    ],
    "createdAt": "2021-02-19T10:40:04.672+05:30",
    "updatedAt": "2021-02-19T10:40:05.815+05:30"
}
Code Copied

Endpoint URI: /newindividual

POST/api/v1/ifi/{ifiID}/applications/newIndividual

Input Parameters

Parameters Description
ifiID Required. Unique identifier of the IFI.
formID Optional. Unique identifier of the form. If specified, value must be unique for each request.
applicationType Required. Type of Application being created. Allowed values: KYC, CREATE_ACCOUNT_HOLDER, EDIT_ACCOUNT_HOLDER. As we are creating an Account Holder, set the value to CREATE_ACCOUNT_HOLDER.
description Description of the Application. Use the parameter to add comments regarding the Application or the Account Holder.
individualType Required. Type of Account Holder being created. As the Application is for a real account holder , set the value as REAL.
individualID Optional. Unique identifier of the Account Holder.
salutation Optional. Salutation using which the Account Holder is addressed. Example: Mr., Mrs., Ms.
firstName, middleName, lastName Optional. Account Holder’s first, middle and last name.
profilePicURL Optional. Link to Account Holder’s profile image.
gender Optional. Account Holder’s gender.
mothersMaidenName Optional. Account Holder’s mother’s maiden name.
dob Account Holder’s date of birth details.
year Optional. Year of birth in YYYY format.
month Required. Month of birth in MM format. Value must be between 1 and 12
day Required. Day of birth in DD format. Value cannot be more than the number of days in the specified month. For example, if the month of birth is June, day must be 30 or less.
Vectors Account Holder’sVector details.
type Optional. Type of Vector.
Allowed values: p for phone number; e for email.
value Optional. Value based on Vector type specified. For example, if vectorType is p, specify Account Holder’s phone number; if vectorType is e, specify email ID.
isVerified Optional. Specify whether the Vector is verified or not. Allowed values: true, false. If the parameter is omitted or any other value is specified, it is set to false.
kycDetails Account Holder’s KYC details.
authType Optional. Type of document submitted for KYC. Allowed values: AADHAR, PAN, PASSPORT, VOTER_ID, DRIVING_LICENSE.
authData Required. Details based on the KYC type specified in authType. For example, if PAN is specified, provide the ten-character PAN identifier.
expiryTime Optional. Expiry time of KYC in the ISO 8601 format YYYY-MM-DD'T'HH:MM:SS:sss'Z'
kycAttributes Optional. Additional information related to KYC.
kycStatus Optional. KYC status of the Account Holder. Supported values:MINIMAL, AADHAR_OTP,
kycStatusPostExpiry Optional. Status of KYC post expiry.
UpdateTime Optional. ISO 8601 Format YYYY-MM-DD'T'HH:MM:SS:sss'Z'
customFields Optional. Any additional information you want to capture. Example: alternate phone number, UCIC.
pops Optional. Account Holder’s address details.
tags Optional. A mechanism for classifying and filtering objects in Fusion.
cURL Sample
Switch Theme
Expand More
Copy 
curl --location --request POST '{{fusion_base_url}}/api/v1/ifi/{{ifiID}}/applications/newIndividual' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{token}} \
--header 'Cache-Control: no-cache' \
--data-raw '{
    "ifiID": "140793",
    "formID": "testapplication123468887",
    "spoolID": "123",
    "individualType": "REAL",
    "salutation": "Mr.",
    "firstName": "Komal",
    "middleName": "",
    "lastName": "Gitika",
    "profilePicURL": "",
    "dob": {
        "year": 1992,
        "month": 7,
        "day": 5
    },
    "gender": "FEMALE",
    "mothersMaidenName": "Rashmi",
    "kycDetails": {
        "kycStatus": "MINIMAL",
        "kycStatusPostExpiry": "string",
        "kycAttributes": {},
        "authData": {
            "PAN": "GRUR08890L"
        },
        "authType": "PAN"
    },
    "vectors": [
        {
            "type": "p",
            "value": "+919123456783",
            "isVerified": false
        }
    ],
    "pops": [],
    "customFields": {
        "companyID": [
            1,
            2,
            3
        ]
    },
    "tags": [
        {
            "type": "vbo",
            "value": "swiggy",
            "isVerified": false
        }
    ],
    "source": "postman"
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy 
  {
    "applicationID": "3791050",
    "formID": "testapplication123468887",
    "ifiID": 140793,
    "spoolID": "123",
    "status": "APPROVED",
    "individualID": "9be6a3ad-a6f1-494a-bb2a-d488c5bac1f2",
    "applicationType": "REAL",
    "salutation": "Mr.",
    "firstName": "Komal",
    "middleName": "",
    "lastName": "Gitika",
    "profilePicURL": "",
    "dob": {
        "year": 1992,
        "month": 7,
        "day": 5
    },
    "gender": "FEMALE",
    "mothersMaidenName": "Rashmi",
    "vectors": {
        "1e34d4d7-58c5-4f50-844b-38a28072ab16": {
            "type": "pan",
            "value": "GRUR08890L",
            "isVerified": false,
            "tags": [
                {
                    "type": "vbo-id",
                    "value": "258cdc62-93cf-46de-8f22-a78f69065ca7"
                }
            ]
        },
        "cc1d9534-84de-4aa3-bcd4-6d8318d5b608": {
            "type": "p",
            "value": "+919123456783",
            "isVerified": false,
            "tags": [
                {
                    "type": "vbo-id",
                    "value": "258cdc62-93cf-46de-8f22-a78f69065ca7"
                }
            ]
        }
    },
    "pops": {},
    "tags": {
        "e859e1f9-615e-4070-9352-78cadb1fe762": {
            "type": "vbo-id",
            "value": "258cdc62-93cf-46de-8f22-a78f69065ca7"
        }
    },
    "kycDetails": {
        "kycStatus": "MINIMAL",
        "updateTime": "Mar 18, 2021 1:50:56 PM",
        "expiryTime": "Feb 23, 2120 1:50:56 PM",
        "kycStatusPostExpiry": "MINIMAL",
        "authType": "PAN",
        "authData": {
            "PAN": "GRUR08890L"
        },
        "kycAttributes": {
            "pan": "GRUR08890L",
            "kycType": "MINIMAL",
            "authType": "PAN"
        }
    },
    "customFields": {
        "companyID": [
            1.0,
            2.0,
            3.0
        ]
    },
    "createdAt": "Mar 18, 2021 1:50:56 PM",
    "updatedAt": "Mar 18, 2021 1:50:56 PM",
    "source": "Fusion",
    "statusDetails": {},
    "dedupeDetails": {
        "updated": false,
        "accountHolderExists": true
    },
    "headers": {}
}
Code Copied

Case 1: Doesn’t exist, i.e. new application

If an account holder doesn’t already exist with the IFI, the account holder will be created after IFI’s review. Fintechs can subscribe to webhooks ( Fusion Events) to be notified when the application is updated

Case 2: Already exists

  • The /accountHolders/{accountHolderID} is then invoked by the fintech to request account holder details.

  • The response payload hence received will contain the KYC status (kycStatus) of the account holder. Below are the KYC statuses:

    • Full: Complete KYC of the account holder is done, i.e. the Aadhar XML, Aadhaar OTP or Aadhaar biometric KYC have already been completed
    • Minimal: Phone number and OVD details of the account holder have been verified
    • Shortfall: The KYC status of the account holder is incomplete, i.e. either the phone number, OVD details or both have not been verified yet.

The Fintech need not re-verify the KYC if:

  • The KYC status is already ‘Full’
  • The Account Holder’s existing KYC status is the same as that of the KYC requirement of the fintech. For example, if the required KYCstatus is ‘minimal’ as was required by the Fintech, then they need not re-do the KYC.

Update KYC Status from ‘Shortfall’ to ‘Minimal’

Fintech will invoke accountHolders/{{account_holder_id}}/createApplication to request an update of KYC status from ‘shortfall’ to ‘minimal’ by passing respective KYC details- contact number and OVD details, in request body. This creates an ‘update Account Holder’ application internally in the Fusion system. This application will then go through the defined approval workflow by the issuer. Once Account Holder’s KYC status is updated successfully, Fintech can issue products to it.

POST/api/v2/ifi/{{ifiID}}/accountHolders/{{account_holder_id}}/createApplication

Input Parameters

Parameters Description
X-Zeta-AuthToken It should be same as the VBO token
ifiID It represents a unique identifier assigned to the IFI (Example: 140793)
Auth_Token Respective Auth Token
requestId Request ID has to be unique per request
accountHolderId The Account Holder for which the KYC has to be updated
operationType KYC_SHORTFALL_TO_MIN

(This value will remain constant for Shortfall to Minimum KYC update)

kycStatus MINIMAL

(The value has to be "MINIMAL" only in the request body)

kycStatusPostExpiry MINIMAL

(The value has to be "MINIMAL" only in the request body)

authType The authentication type on which the user is onboarded
authdata Details of the "authType"
cURL Sample
Switch Theme
Expand More
Copy 
curl --location --request POST 'https://fusion.preprod.zeta.in/api/v2/ifi/{{ifiID}}/accountHolders/{{account_holder_id}}/createApplication' \
--header 'X-Zeta-AuthToken: {{a}}' \
--header 'Content-Type: application/json' \
--header 'Cookie: AWSALB=dh7EbNqWqkugWqKeUbVQB0/o72Vf8zsTC3VQC/R8YrqKAqzzi1cySVnmZ2ytG5bG4j5SoKpzzjHWjQ1VLTD5mshAr25h+df0dSTeFi+dASJ1ngehHhRC8XNs1wdv; AWSALBCORS=dh7EbNqWqkugWqKeUbVQB0/o72Vf8zsTC3VQC/R8YrqKAqzzi1cySVnmZ2ytG5bG4j5SoKpzzjHWjQ1VLTD5mshAr25h+df0dSTeFi+dASJ1ngehHhRC8XNs1wdv' \
--data-raw '{
 "requestId": "request_kyc_19110102",
 "operationType": "KYC_SHORTFALL_TO_MIN" ,
 "reqPayload": {
   "kycStatus": "MINIMAL",
   "kycStatusPostExpiry": "MINIMAL",
   "authType": "PAN",
   "authdata": {
     "pan": "FYUBH9654N"
   }
 }
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy 
{
    "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
    "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
    "ifiId": 140793,
    "status": "ENRICHMENT_INITIATED",
    "sections": {
        "KycDetails": {
            "sectionId": "79ba3104-d103-451f-9e53-8b354fe5be93",
            "ifiId": 140793,
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "name": "KycDetails",
            "type": "KYC",
            "details": {
                "kycPayload": {
                    "ifiId": "140793",
                    "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
                    "authType": "PAN",
                    "authdata": {
                        "pan": "FFGPK9954E"
                    },
                    "kycStatus": "MINIMAL",
                    "accountHolderId": "eed858de-e7c9-4db4-a48d-58ecd8aea65a",
                    "kycStatusPostExpiry": "MINIMAL"
                }
            },
            "createdAt": "2020-11-18T23:01:26.914+05:30",
            "updatedAt": "2020-11-18T23:01:26.914+05:30"
        }
    },
    "vectors": [],
    "stages": [
        {
            "stageId": "43f85181-be16-498c-a1cf-ebbb90c7babc",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "DATA_CAPTURE",
            "status": "COMPLETED",
            "details": {},
            "result": {
                "validationPassed": {
                    "validation": "successful"
                }
            },
            "createdAt": "2020-11-18T23:01:27.479+05:30",
            "updatedAt": "2020-11-18T23:01:36.830+05:30"
        },
        {
            "stageId": "f55678da-7312-41d1-add9-209a985a4445",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "ASSESSMENT",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2020-11-18T23:01:27.851+05:30",
            "updatedAt": "2020-11-18T23:01:27.851+05:30"
        },
        {
            "stageId": "7d25b3c6-b4b4-4269-99a6-c6e6984c5d93",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "PROVISIONING",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2020-11-18T23:01:27.851+05:30",
            "updatedAt": "2020-11-18T23:01:27.851+05:30"
        },
        {
            "stageId": "30d1110c-668f-44f5-9b81-046f3bb85bb0",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "REVIEW",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2020-11-18T23:01:27.855+05:30",
            "updatedAt": "2020-11-18T23:01:27.855+05:30"
        },
        {
            "stageId": "21e6d195-a7d0-4473-9379-60aa87a4916a",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "ENRICHMENT",
            "status": "INITIATED",
            "details": {},
            "result": {
                "validationPassed": {
                    "validation": "successful"
                }
            },
            "createdAt": "2020-11-18T23:01:27.871+05:30",
            "updatedAt": "2020-11-18T23:01:38.883+05:30"
        }
    ],
    "tags": [
        {
            "type": "spool-id",
            "value": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "attributes": {}
        }
    ],
    "createdAt": "2020-11-18T23:01:25.555+05:30",
    "updatedAt": "2020-11-18T23:01:37.418+05:30"
}
Code Copied

Update KYC Status to Full KYC

The Full KYC is facilitated as per the respective IFI’s preference. For example, the RBL bank enables full KYC via Aadhaar XML KYC and Aadhaar Biometric KYC while IDFC Bank supports Aadhaar OTP KYC. The fintechs shall subscribe to any of the KYC methods provided by their IFIs to be able to get the Full KYC done for their users.

Application Status

After the application is successfully created, it is submitted to the Issuer for review. Based on the details submitted and the qualifying criteria set, the issuer approves or rejects the application. If the application is rejected, fintechs are suggested to address the reason and re-submit the application..

Fintechs shall configure the webhooks for the same to be notified of the update on the application. For more information on webhook events, please refer to Fusion Events

Keep track of this space for more updates


Related articles

Fusion Events

List of webhooks to subscribe to & receive event notification

Account Holders FAQs

FAQs related to the Account Holders

Account Holder API Error Codes

List of error codes specific to Account Holder APIs

Generic Error Codes

List of general error codes across fusion

Manage Account Holder

Learn about managing applications & account holder

Application APIs

APIs to create and manage application

Account Holder APIs

Create Account Holders, and update account details

KYC Basics

An introduction to the key KYC concepts