Introduction

The FP API is designed to be easily predictable and have consistency across all the resources. It accepts json in the request body and returns a json representation of the resource. We use standard HTTP response codes and HTTP verbs.

You can access FP API in sandbox and production modes separately. Use the following base URLs:
Sandbox (for testing): https://s.finprim.com
Production (for live transactions): https://api.fintechprimitives.com

Authentication

FP API uses bearer auth to authenticate all the api calls. You need to send the following header in all your api calls along with your access token:

Authorization: Bearer ACCESS_TOKEN

Generate the access token

Refer to the login api documentation here

KYC Requests

This endpoint can be used to create a KYC application. Even though values for name, pan, email, date_of_birth and mobile fields are required to create a KYC application and generate an OTP, all the required information must be collected from the KYC non-compliant user in order to perform eSign and complete the KYC application submission. At any point in time you can refer to requirements.fields_needed attribute in the KYC object to check the fields for which the values are required.

Endpoints:

POST /v2/kyc_requests
GET /v2/kyc_requests/:id
GET /v2/kyc_requests
PATCH /v2/kyc_requests
POST /v2/kyc_requests/:id/simulate

Basic workflow

1. Create a KYC application by providing values for name, pan, email, date_of_birth and mobile. The KYC request will be in pending state at this stage. You can check the state by referring to the status attribute in the KYC object.

2. Provide all the required information to eSign and submit the KYC application that is created. You can also check the requirements.fields_needed section in the KYC object to see the list of fields which are yet to be input.

3. Once all the required details are provided, the KYC application moves from pending to esign_required state. Please note that this process might take 1-2 minutes (approx.) in production environment as the bank account details are verified in the background.

4. Once the state of the KYC application changes to esign_required, Esign API should be used to create an esign object. Redirect the user to redirect_url in the esign object in order to perform the eSign.

5. Once the user completes the eSign process successfully, the KYC application will be submitted and state moves from esign_required to submitted.

6. Now our AMC partner would have received the KYC application that was submitted and the verification process begins, post which the application will be moved to either successful or rejected state

KYC Request Object

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  },
  "requirements": {
    "fields_needed": [
      "ipv_video"
    ]
  }
}

Attribute	Type	Comments
object	string	Value is kyc_request. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the kyc_request object
name	string	Full name of the investor
pan	string	PAN number of the investor
email	string	Email id of the investor
mobile	hash	Mobile number of the investor
date_of_birth	string	Date of birth of the investor
aadhaar_number	string	Last 4 digits of the investor's aadhaar number
father_name	string	Investor's father name
spouse_name	string	Investor's spouse name
mother_name	string	Investor's mother name
gender	enum	Investor's gender. Possible values: male, female, transgender
country_of_birth	enum	Investor's country of birth in ISO 3601 2 alphabet code
marital_status	enum	Investor's marital status. Possible values: married, unmarried, others
residential_status	enum	This determines the investor's residential status for tax purposes. Possible values: resident_individual
occupation_type	enum	Investor's occupation details. Possible values: business, professional, self_employed, retired, housewife, student, public_sector, private_sector, government_sector, others
geolocation	hash	Location of the investor from where the kyc application is submitted. It contains latitude and longitude
bank_account	hash	Investor's bank account details. Contains account_holder_name, account_number, ifsc_code, proof
address	hash	Address for all correspondence
identity_proof	string	Copy of investor's pan card
ipv_video	string	Verification video
signature	string	Investor's signature
photo	string	Investor's photograph
otp	string	Verification code for the video. The code has no expiration time.
status	string	The status of the kyc request. Can be pending, esign_required, submitted, successful, rejected
created_at	string	The timestamp at which the kyc request object is created
expires_at	string	The timestamp at which the kyc request object expires
verification	hash	The details of the verification status of the data submitted
requirements	hash	Feedback on the data requirements. It contains fields_needed which represent the list of fields that are required for procesing the KYC Request

verification hash

A snippet of verification hash from the KYC Request object

{
  // showing only a part of KYC Request object
  "verification": {
    "status": "rejected",
    "details": {
      "pan": "data_mismatch",
      "signature": "data_missing",
      "address.proof": "document_unclear"
    },
    "details_verbose": {
      "pan": {
        "code": "data_mismatch",
        "reason": "Invalid pan"
      },
      "signature": {
        "code": "data_missing",
        "reason": "Signature not available"
      },
      "address.proof": {
        "code": "document_invalid",
        "reason": "Proof of address not valid; Translation into english is required"
      }
    }
  }
}

Attribute	Type	Comments
status	string	Status of the verification. Can be pending, esign_required, submitted, successful, rejected
details	hash	If the verification status is rejected, this contains the details about the rejection. Keys of this hash represent the fields in the kyc request object and value can be data_missing, data_mismatch, document_unclear, document_invalid
details_verbose	hash	If the verification status is rejected, this contains the details about the rejection along with a reason text. Keys of this hash represent the fields in the kyc request object and value is a hash with code and reason keys. code is the same as in the details hash

Create a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "pan": "K1PPG1998U",
  "email": "raj@example.com",
  "aadhaar_number": "1210",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": "",
  "mother_name": "Neha Gupta",
  "gender": "male",
  "date_of_birth": "1980-10-19",
  "country_of_birth": "in",
  "marital_status": "unmarried",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "address": {
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "city": "Delhi",
    "pincode": "110001",
    "country": "in",
    "proof": "4192de0d-165f-458e-89ec-d4334b370256",
    "proof_back": "771a4d57-5447-4b1e-b4b6-dcb6049bda8c",
    "proof_type": "passport",
    "proof_number": "JXXXXXX0",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "identity_proof": "2f4d93e0-b700-41b8-b78e-e130224cfb03",
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172"
}

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  },
  "requirements": {
    "fields_needed": [
      "ipv_video"
    ]
  }
}

The endpoint is used to submit a KYC request to the platform.

HTTP Request

POST /v2/kyc_requests

Query Parameters

Name	Mandatory*	Type	Comments
name	yes	string	name of the investor
pan	yes	string	should be a valid individual pan number
email	yes	string	email ID of the investor to be reported to AMC
date_of_birth	yes	string	date of birth in yyyy-mm-dd format
mobile	yes	object
aadhaar_number	no	string	last 4 digits of aadhaar
father_name	no	string	mandatory if spouse_name is not mentioned
spouse_name	no	string	mandatory if father_name is not mentioned
mother_name	no	string
gender	no	string	gender of the investor. Values permitted: male, female, transgender
country_of_birth	no	string	investor's country of birth in ISO 3601 2 alphabet code
marital_status	no	string	marital status of the investor. Values permitted: married, unmarried, others
residential_status	no	string	residential status of the investor. Values permitted: resident_individual
occupation_type	no	string	occupation of the investor. Values permitted: business, professional, self_employed, retired, housewife, student, public_sector, private_sector, government_sector, others
address	no	object
identity_proof	no	string	(ID of File) PAN card image. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
ipv_video	no	string	(ID of File) verification video of the investor. File must be in mp4 format and size should not exceed 10 MB.
signature	no	string	(ID of File) copy of the wet signature of the investor. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
photo	no	string	(ID of File) investor's photo. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
geolocation	no	object	Location details of the investor from where the kyc application is submitted
bank_account	no	object	Investor's bank account details

Mobile params

Name	Mandatory	type	Comments
isd	yes	string	isd code of country
number	yes	string	mobile number

Address params

Name	Mandatory	type	Comments
line_1	yes	string	address line 1
line_2	no	string	address line 2
line_3	no	string	address line 3
city	yes	string	city name
pincode	yes	string	valid area pincode
country	yes	string	country in ISO 3601 2 alphabet code
proof	yes	string	(ID of File) copy of the address proof. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
proof_back	no	string	(ID of File) copy of the back side of the address proof. Required if proof_type is voter_id, passport and driving_licence. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
proof_type	yes	string	one of passport, voter_id, driving_licence
proof_number	yes	string	valid number mentioned on the address proof
proof_issue_date	no	string	Required if proof_type is passport, driving_licence. Should be in past in yyyy-mm-dd format
proof_expiry_date	no	string	Required if proof_type is passport, driving_licence. Should be in future in yyyy-mm-dd format

Geolocation

Name	Mandatory	type	Comments
latitude	yes	float	Geolocation latitude
longitude	yes	float	Geolocation longitude

Bank Account

Name	Mandatory	type	Comments
account_holder_name	yes	string	Name of the bank account holder
account_number	yes	string	Account number on cancelled cheque document
ifsc_code	yes	string	IFSC code of the bank
proof	yes	string	(ID of File) cancelled cheque image. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.

Fetch a kyc request

curl -X GET "https://s.finprim.com/v2/kyc_requests/123"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "rejected",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "ipv_video": "02651d2a-38fc-42a2-8c20-221d10453b3c",
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "requirements": {
    "fields_needed": [

    ]
  },
  "verification": {
    "status": "rejected",
    "details": {
      "pan": "data_mismatch",
      "signature": "data_missing",
      "address.proof": "document_unclear"
    },
    "details_verbose": {
      "pan": {
        "code": "data_mismatch",
        "reason": "Invalid pan"
      },
      "signature": {
        "code": "data_missing",
        "reason": "Signature not available"
      },
      "address.proof": {
        "code": "document_invalid",
        "reason": "Proof of address not valid; Translation into english is required"
      }
    }
  }
}

The endpoint is used to fetch the details of a KYC request.

HTTP Request

GET /v2/kyc_requests/:id

Query Parameters

Parameter	Mandatory	Default	Description
id	yes	-	id of the KYC Request

Status Descriptions - verification.status

Value	Description
pending	The KYC request has been created. It will be sent to AMC when all the required fields are provided.
esign_required	Investor details document needs to be eSigned for the kyc request to be processed further.
submitted	The KYC request has been submitted to the AMC
successful	The KYC request has been successfully processed by the AMC
rejected	The KYC request has been rejected

Verification Details

Value	Description
data_mismatch	The data provided in the input is not matching with the document
document_invalid	The provided document is not valid
document_unclear	The provided document is not clear to read
data_missing	The data point is completely missing

Details Verbose

Name	Comments
code	Value is same as Verification Details
reason	Rejection messages separated by semicolon

List all kyc requests

curl -X GET "https://s.finprim.com/v2/kyc_requests?pan=K1PPG1998U&status=rejected,pending"
-H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "list",
  "data": [
    {
      "object": "kyc_request",
      "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
      "status": "rejected",
      "aadhaar_number": "1210",
      "pan": "K1PPG1998U",
      "name": "Rani Gupta",
      "father_name": "Rajesh Gupta",
      "spouse_name": null,
      "mother_name": null,
      "email": null,
      "mobile": null,
      "ipv_video": "02651d2a-38fc-42a2-8c20-221d10453b3c",
      "signature": null,
      "photo": null,
      "gender": "male",
      "date_of_birth": "1981-01-15",
      "marital_status": "married",
      "country_of_birth": "in",
      "address": {
        "city": "Delhi",
        "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
        "line_1": "E/&02",
        "line_2": "Opp SBI ATM",
        "line_3": "12th Main Road South Delhi",
        "country": "in",
        "pincode": "401012",
        "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
        "proof_type": "passport",
        "proof_number": "JXXXXXXA",
        "proof_issue_date": "2004-10-20",
        "proof_expiry_date": "2020-10-20"
      },
      "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
      "residential_status": "resident_individual",
      "occupation_type": null,
      "created_at": "2019-11-09T13:26:38.946+0530",
      "expires_at": "2019-11-09T13:26:38.946+0530",
      "otp": "9bbf32",
      "geolocation": {
        "latitude": 12.354,
        "longitude": 77.453
      },
      "bank_account": {
        "account_holder_name": "Rani Gupta",
        "account_number": "919017057965811",
        "ifsc_code": "UTIB0003093",
        "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
      },
      "requirements": {
        "fields_needed": [

        ]
      },
      "verification": {
        "status": "rejected",
        "details": {
          "pan": "data_mismatch",
          "signature": "data_missing",
          "address.proof": "document_unclear"
        },
        "details_verbose": {
          "pan": {
            "code": "data_mismatch",
            "reason": "Invalid pan"
          },
          "signature": {
            "code": "data_missing",
            "reason": "Signature not available"
          },
          "address.proof": {
            "code": "document_invalid",
            "reason": "Proof of address not valid; Translation into english is required"
          }
        }
      }
    },
    {
      "object": "kyc_request",
      "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
      "status": "pending",
      "aadhaar_number": "1210",
      "pan": "K1PPG1998U",
      "name": "Rani Gupta",
      "father_name": "Rajesh Gupta",
      "spouse_name": null,
      "mother_name": null,
      "email": null,
      "mobile": null,
      "signature": null,
      "photo": null,
      "gender": "male",
      "date_of_birth": "1981-01-15",
      "marital_status": "married",
      "country_of_birth": "in",
      "address": {
        "city": "Delhi",
        "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
        "line_1": "E/&02",
        "line_2": "Opp SBI ATM",
        "line_3": "12th Main Road South Delhi",
        "country": "in",
        "pincode": "401012",
        "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
        "proof_type": "passport",
        "proof_number": "JXXXXXXA",
        "proof_issue_date": "2004-10-20",
        "proof_expiry_date": "2020-10-20"
      },
      "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
      "residential_status": "resident_individual",
      "occupation_type": null,
      "created_at": "2019-11-09T13:26:38.946+0530",
      "expires_at": "2019-11-09T13:26:38.946+0530",
      "otp": "9bbf32",
      "geolocation": {
        "latitude": 12.354,
        "longitude": 77.453
      },
      "bank_account": {
        "account_holder_name": "Rani Gupta",
        "account_number": "919017057965811",
        "ifsc_code": "UTIB0003093",
        "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
      },
      "requirements": {
        "fields_needed": [
          "ipv_video"
        ]
      },
      "verification": {
        "status": "pending",
        "details": null,
        "details_verbose": null
      }
    }
  ]
}

The endpoint is used to fetch the list of KYC requests.

HTTP Request

GET /v2/kyc_requests

Query Parameters

Name	Mandatory*	Type	Comments
pan	No	string	PAN number
status	No	string	Can be pending, esign_required, submitted, successful, rejected. Multiple values are supported by , seperator.

Update a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests/6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "identity_proof": "1411ff9c-3b68-4c5c-bfe7-46f1a1cdd7f6",
  "ipv_video": "76e18d5f-e84a-478d-a836-4971f38d3814"
}

The endpoint is used to update the details of a KYC request

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "1411ff9c-3b68-4c5c-bfe7-46f1a1cdd7f6",
  "ipv_video": "76e18d5f-e84a-478d-a836-4971f38d3814",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  },
  "requirements": {
    "fields_needed": [

    ]
  }
}

HTTP Request

POST/PATCH /v2/kyc_requests/:id

Request/Response same as Create KYC Request

Simulate a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests/6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21/simulate"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "status": "successful"
}

The endpoint is used to simulate the status of a KYC request

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "successful",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "ipv_video": "02651d2a-38fc-42a2-8c20-221d10453b3c",
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "requirements": {
    "fields_needed": [

    ]
  },
  "verification": {
    "status": "successful",
    "details": null,
    "details_verbose": null
  }
}

HTTP Request

POST /v2/kyc_requests/:id/simulate

Query Parameters

Name	Mandatory*	Type	Comments
status	yes	string	expected status of the kyc request. Values permtted: successful, rejected, expired. For successful or rejected, the KYC request must be in submitted state. For expired, the KYC request must be in pending or esign_required state

Esigns

Use this to complete the Esign process for the KYC request.

Endpoints:

POST /v2/esigns
GET /v2/esigns/:id

Esign Object

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "pending",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

Attribute	Type	Comments
object	string	Value is esign. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the esign object
type	string	Type of the esign. Can be aadhaar
kyc_request	string	KYC Request for which this esign is being processed for
redirect_url	string	Url for starting the esign process
status	string	Status of the esign. Can be pending, successful
postback_url	string	Url to which you will be redirected once esign process is complete
created_at	string	The timestamp at which the esign object is created

* The redirect_url can be used multiple times in case the user is not able to complete the esign process

Create an esign

curl -X POST "https://s.finprim.com/v2/esigns"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "postback_url": "http://localhost:3000"
}

JSON response:

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "pending",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

The endpoint is used to create an esign

HTTP Request

POST /v2/esigns

Query Parameters

Name	Mandatory*	Type	Comments
kyc_request	yes	string	id of the kyc_request to which it is related
postback_url	yes	string	The URL to which you want be redirected once the esign process is complete.

Postback response

After the esign process is completed, we redirect the user to postback_url with the following query parameters

Name	Value
esign	id of the esign object
status	status of the esign.

Fetch an esign

curl -X GET "https://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "successful",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

The endpoint is used to fetch an esign

HTTP Request

GET /v2/esigns/:id

Query Parameters

Name	Mandatory*	Type	Comments
id	yes	string	id of the esign

Parses

Represents parse operation. This API can be used to parse a consolidated account statement or CAS file. We support CAS files - Detailed type of Karvy and CAMS.

Upload CAS file in Files API Refer before using parser service. File service returns id once you have uploaded the file, use this to perform parsing.

Note: Non commercial transactions are not parsed.

A typical parse object contains the following fields.

Parse Object

{
  "id": "parse_a7b0f278604d46d8a847fde20da1b4e7",
  "object": "parse",
  "status": "processed",
  "file": "file_fe8a573f4a6b4a68be04d26e7aa164a0",
  "outcome": [
    {
      "pan": "AMXXXXXX9M",
      "advisor": "ARN-2590",
      "registrar": "FTAMIL",
      "folio_number": "180111958/0",
      "transactions": [
        {
          "date": "2013-01-31",
          "type": "purchase",
          "amount": 11000,
          "units": 44.972,
          "price": 244.595,
          "unit_balance": 44.972
        }
      ],
      "scheme_code": "FTI034",
      "scheme_name": "0349905131566 Franklin India Taxshield - GROWTH",
      "opening_balance": 0,
      "closing_balance": 44.972,
      "calculated_closing_balance": 44.972
    }
  ],
  "reason": null,
  "created_at": "2020-06-18T14:16:13+05:30"
}

Attribute	Type	Comments
object	string	Value is parse. String representing the object type. Objects of the same type share the same value.
id	string	Unique identifier for the parse object created
file	string	File id used to create parse request
status	string	Status of the parse request. Can be pending, processed, and failed
outcome	list	Contains the transactions parsed from the file
reason	string	Contains reason if status is failed
created_at	timestamp	Date and time when the parse object was created

Outcome attributes

Attribute	Type	Description
pan	string	PAN number of the investor
advisor	string	ARN code or RIA code of the distributor/advisor as seen in the CAS file
registrar	string	RTA identifier
folio_number	string	Folio number
scheme_code	string	Scheme code. Refer Single Fund Schemes Detail API for scheme code details
scheme_name	string	Scheme name as it appears in the CAS file. Any scheme name which is spread across more than one line is truncated.
reverse_product_code	string	Unique code to identify a scheme.
transactions	list	List of transactions. The order will remain the same as in the CAS file.
opening_balance	decimal	Opening balance
closing_balance	decimal	Closing balance
calculated_closing_balance	decimal	Computed closing balance in parser service based on difference between credit and debits in the transactions. This can be used for reconciliation purposes.

Transaction attributes

Attribute	Type	Description
date	date	Date of transaction
type	string	Supported transaction types are sip, purchase, redemption, switch_in, switch_out and reversal
amount	decimal	Refers to the amount which investor have invested, transferred or withdrawn or the dividend amount being paid or reinvested
units	decimal	Number of units allotted or redeemed
price	decimal	Transaction NAV
unit_balance	decimal	Holding units after the end of this particular transaction

Create a parse

curl -X POST "https://s.finprim.com/v2/parses"
-H "Authorization: Bearer JWTTOKEN"
-d
'{
    "file" : "file_fe8a573f4a6b4a68be04d26e7aa164a0",
    "password": "password"
}'

The above command returns a JSON similar to one below:

{
  "id": "parse_a7b0f278604d46d8a847fde20da1b4e7",
  "object": "parse",
  "status": "pending",
  "file": "file_fe8a573f4a6b4a68be04d26e7aa164a0",
  "outcome": null,
  "created_at": "2020-06-18T14:16:13+05:30"
}

This API is for submitting a request to parse the file.

HTTP Request

POST /v2/parses

Query Parameters

Parameter	Mandatory	Default	Description
file	yes	-	id of the file to parse. Refer file-operations to upload a file. File type should be in pdf format.
password	no	-	Password to open the CAS file.

Fetch a parse

curl "https://s.finprim.com/v2/parses/parse_a7b0f278604d46d8a847fde20da1b4e7"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns a JSON similar to one below

{
  "id": "parse_a7b0f278604d46d8a847fde20da1b4e7",
  "object": "parse",
  "status": "processed",
  "file": "file_fe8a573f4a6b4a68be04d26e7aa164a0",
  "outcome": [
    {
      "pan": "AMXXXXXX9M",
      "advisor": "ARN-2590",
      "registrar": "FTAMIL",
      "folio_number": "180111958/0",
      "scheme_code": "FTI034",
      "scheme_name": "Franklin India Taxshield - GROWTH",
      "reverse_product_code": "FITGP",
      "transactions": [
        {
          "date": "2013-01-31",
          "type": "purchase",
          "amount": 11000,
          "units": 44.972,
          "price": 244.595,
          "unit_balance": 44.972
        },
        {
          "date": "2013-02-01",
          "type": "sip",
          "amount": 1000,
          "units": 4.098,
          "price": 244.0149,
          "unit_balance": 49.07
        }
      ],
      "opening_balance": 0,
      "closing_balance": 49.07,
      "calculated_closing_balance": 49.07
    }
  ],
  "reason": null,
  "created_at": "2020-06-18T14:16:13+05:30"
}

This API is used to fetch the parsed details.

HTTP Request

GET /v2/parses/:id

Query Parameters

Parameter	Mandatory	Default	Description
id	yes	-	id returned from create parse request api.

MF Investment Accounts

You need to create an investment account for your investors before you can start accepting orders. Any orders placed via an investment account and folios associated with those orders are organized under the investment account. When you migrate folios, folios having the same pans and holding pattern combination are organized under the investment accounts of matching pans and holding pattern. mf_investment_account object represents such investment accounts.

Endpoints:

POST /v2/mf_investment_accounts
PATCH /v2/mf_investment_accounts
GET /v2/mf_investment_accounts/:id
GET /v2/mf_investment_accounts

MF Investment Account Object

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Attribute	Type	Comments
object	string	Value is mf_investment_account. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_investment_account object
old_id	integer	This id is the V1 id of this investment account object. We have provided this id for backward compatibility purposes, and you can use this id in V1 APIs. However, please use V2 object ids and V2 APIs wherever possible
primary_investor_pan	string	PAN of the first holder
second_investor_pan	string	PAN of the second holder
third_investor_pan	string	PAN of the third holder
primary_investor_old_id	string	V1 identifier of the first investor object attached to this investment account
second_investor_old_id	string	V1 identifier of the second investor object attached to this investment account
third_investor_old_id	string	V1 identifier of the third investor object attached to this investment account
holding_pattern	string	this value indicates the holding nature of the folios that are mapped against this investment account. For example, if the holding pattern is single, you can create transactions against investor's folios where the investor is the primary investor and holding pattern is single. Possible values: single, joint, either_or_survivor, anyone_or_survivor, first_or_survivor
created_at	string	The time at which the investment_account is created

Create a mf investment account

POST /v2/mf_investment_accounts

curl -X POST "https://s.finprim.com/v2/mf_investment_accounts"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "primary_investor_old_id": 109,
  "holding_pattern": "single"
}

JSON Response:

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
primary_investor_old_id	yes	string	Provide V1 investor id of the first holder
holding_pattern	no	string	Provide holding pattern for the investment account. Supported values: single

Update a mf investment account

PATCH /v2/mf_investment_accounts

This API lets you associate an investor with an investment account. This will be necessary when you avail FP's folio migration facility. When folios are migrated, corresponding investment accounts are created and folios are organized under the investment accounts. No investor objects are created. Therefore, there will be investment accounts without any investor associated with them. When you onboard an investor, you can search whether there are any investment accounts are present or not. If they are present, you can associate an investor with the investment account using this API.

curl -X PATCH "https://s.finprim.com/v2/mf_investment_accounts/mfia_14bafabfbfbc423d9b54412dd577981b"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "primary_investor_old_id": 109
}

JSON Response:

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 Id of the investment account.
primary_investor_old_id	yes	integer	Provide V1 investor id of the first holder. The pan of the investor should match with the primary_investor_pan of the investment account.

Fetch a mf investment account

GET /v2/mf_investment_accounts/:id

This API is used to fetch a given investment account by its V2 identifier.

curl -X GET "https://s.finprim.com/v2/mf_investment_accounts/mfia_14bafabfbfbc423d9b54412dd577981b"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account_id	yes	string	V2 or V1 id of the investment account

List all mf investment accounts

GET /v2/mf_investment_accounts

curl -X GET "https://s.finprim.com/v2/mf_investment_accounts"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_investment_account",
      "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
      "old_id": 110,
      "primary_investor_pan": "ACCPP55K7L",
      "second_investor_pan": null,
      "third_investor_pan": null,
      "primary_investor_old_id": 109,
      "second_investor_old_id": null,
      "third_investor_old_id": null,
      "holding_pattern": "single",
      "created_at": "2020-04-06T15:32:52+05:30"
    },
    {
      "object": "mf_investment_account",
      "id": "mfia_24bafbbfbfbc423d9b54412dc57a9a11",
      "old_id": 111,
      "primary_investor_pan": "PCCPK55K7L",
      "second_investor_pan": null,
      "third_investor_pan": null,
      "primary_investor_old_id": 112,
      "second_investor_old_id": null,
      "third_investor_old_id": null,
      "holding_pattern": "single",
      "created_at": "2020-04-06T15:32:52+05:30"
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
primary_investor_pan	no	string	Filter by primary investor pan.
second_investor_pan	no	string	Filter by second investor pan.
third_investor_pan	no	string	Filter by third investor pan.
holding_pattern	no	string	Filter by holding_pattern of investment account.
investor	no	string	Accepts a PAN as a value. Using this option, you can filter all the investment accounts in which this PAN is present either as primary, secondary or third investor

Note:

The response contains maximum of 100 mf investment accounts ordered by the created date

MF Purchases

Represents a mutual fund purchase order. The purchase order can be a lump sum purchase order or it can be a purchase order created via a purchase plan.

Endpoints:

POST /v2/mf_purchases
PATCH /v2/mf_purchases
GET /v2/mf_purchases/:id
GET /v2/mf_purchases

MF Purchase Object

{
  "object": "mf_purchase",
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "old_id": 9123,
  "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
  "folio_number": "31171511",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FE6",
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-06T15:32:52+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "retried_at": null,
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "plan": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

Attribute	Type	Comments
object	string	Value is mf_purchase. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_purchase object
old_id	integer	This id is the V1 id of this purchase object. We have provided this id for backward compatibility purposes, and you can use this id in V1 APIs. However, please use V2 object ids and V2 APIs wherever possible
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the purchase order using this id
folio_number	string	This value represents the mutual fund folio number. Using the folio number, you can determine the folio in which the investor has made the purchase. In case of fresh purchases, the folio number will be available only when the order becomes successful.
state	string	State of the purchase order. Possible values: pending, confirmed, sumitted, successful, failed, cancelled, reversed
amount	decimal	Purchase amount in Rupees
allotted_units	decimal	Number of units allotted for this purchase transaction. For example, the user might have placed a purchase order for Rs. 500 at a NAV of Rs. 296.0196. A stamp duty at 0.005% of Rs. 500 = 0.03(0.025 rounded up to 0.03) might get applied and the actual investment amount would be 500 - 0.03 = Rs. 499.97. Units allotted = 499.97/296.0196 = 1.68897600024 = 1.689 (Rounded up to 3 decimal points). The value will be available only after the order is submitted to the order gateway and is successfully processed
purchased_amount	decimal	The actual purchase amount. For example, the user might have placed a purchase order for Rs. 500 at a NAV of Rs. 296.0196. A stamp duty at 0.005% of Rs. 500 = 0.03(0.025 rounded up to 0.03) might get applied and the actual investment amount would be 500 - 0.03 = Rs. 499.97. The value will be available only after the order is submitted to the order gateway and is successfully processed.
purchased_price	decimal	NAV at which the trade happened
scheme	string	isin of the scheme in which the investment was made
type	string	This value indicates whether this purchase order is a fresh purchase or an additional purchase in an existing folio. Possible values: purchase, additional_purchase
plan	string	The V2 object id of the plan with which this purchase is associated. This value will be available only if this purchase order is created by a plan
scheduled_on	string	The date on which the order is scheduled for submission to the order gateway(bse or rta) for processing
traded_on	string	The date on which the trade happened. Please note that the trade will happen after the order is submitted to the order gateway
created_at	string	The time at which the order is created
confirmed_at	string	The time at which the order is confirmed
submitted_at	string	The time at which the order is submitted to the order gateway
succeeded_at	string	The time at which the order is processed successfully
failed_at	string	The time at which the order is failed
retried_at	string	The time at which the order is last retried
reversed_at	string	The time at which the order is reversed
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta, ,bse
source_ref_id	string	An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application)
user_ip	string	IP address of end user who has initiated the transaction.
server_ip	string	IP address of server through which the request to create this transaction was made.
euin	string	Unique identity number of the employee / relationship manager/ sales person of the distributor who has advised or interacted with the investor in any other manner for this purchase order.
distributor_id	string	The id of the distributor/ria associated with the purchase order.
failure_code	string	Failure code of the failed purchase order. Possible values: payment_failure,order_expiry,others
initiated_by	string	The entity/person who has initiated this purchase. Possible values: investor, distributor
initiated_via	string	The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web

Create a MF Purchase

POST /v2/mf_purchases

Note:

When you create an order using Create mf_purchase order API, the order will be in the pending state. However, the orders would get submitted to the order gateway only after you mark the order as confirmed. You can use our Update mf_purchase order API to mark an order as confirmed. If you are routing orders via RTA and if you are using our payments API to make payments for orders, orders will get marked as confirmed upon successful payment by FP. In such cases, you need not mark the order as confirmed explicitly. BSE orders will be submitted only if they are marked as confirmed.

An order which is in pending state will be marked as failed due to inactivity after T+1 market day post RTA order submission cut-off time, if the order is not confirmed within this duration.

curl -X POST "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
  "scheme": "INF173K01FE6",
  "folio_number": "31171511",
  "amount": 10000,
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "euin": null
}

JSON Response:

{
  "object": "mf_purchase",
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "old_id": 9123,
  "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
  "folio_number": "31171511",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FE6",
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-06T15:32:52+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "retried_at": null,
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "plan": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	Provide the V2 id of the investment account against which this order must be placed.
scheme	yes	string	Provide the isin of the scheme for which this order must be placed.
folio_number	no	string	Provide the folio number mapped against the investment account if you want to make an additional purchase against a folio.
amount	yes	integer	Provide purchase amount in Rupees. if In case of fresh purchases, the amount should be between min_initial_investment and max_initial_investment and should be a multiple of initial_investment_multiples In case of additional purchases, the amount should be between min_additional_investment and max_additional_investment and should be a multiple of additional_investment_multiples Each scheme has different initial investment amount constraints or additional investment constraints. You can fetch scheme details using Fund Scheme Details API to know the values for such constraints.
user_ip	no	string	Provide IP address of the end-user.
server_ip	no	string	Provide IP address of the server through which the request to create this order is made.
source_ref_id	no	string	An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application).
euin	no	string	Provide EUIN associated with the distributor through which the order is being placed.

Update a MF Purchase

PATCH /v2/mf_purchases

curl -X PATCH "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "state": "confirmed"
}

JSON Response:

{
  "object": "mf_purchase",
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "old_id": 9123,
  "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
  "folio_number": "39171511",
  "state": "confirmed",
  "amount": 10000.0,
  "scheme": "INF173K01FE6",
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-06T15:32:52+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "retried_at": null,
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "plan": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": "2020-04-06T20:32:52+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 Id of the purchase order.
state	yes	string	New state of the purchase order. Supported values: confirmed

Fetch a MF Purchase

GET /v2/mf_purchases/:id

curl -X GET "https://s.finprim.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a given purchase order by its identifier.

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 or V1 id of the purchase order.

JSON Response:

{
  "object": "mf_purchase",
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "old_id": 9123,
  "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
  "folio_number": "31171511",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FE6",
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-06T15:32:52+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "retried_at": null,
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "plan": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

List all MF Purchases

GET /v2/mf_purchases

curl -X GET "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API used to fetch all purchase orders.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 9123,
      "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
      "folio_number": "31171511",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FE6",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "distributor_id": null,
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    },
    {
      "object": "mf_purchase",
      "id": "mfp_266177219f634373b01072986d2eea4d",
      "old_id": 9123,
      "mf_investment_account": "mfia_177a85826694614a531c0f82b196022",
      "folio_number": "11171611",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF373K01FE1",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-02-07",
      "created_at": "2020-03-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app",
      "euin": null,
      "distributor_id": null,
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the purchases are made.

Note:

The response can contain 100 latest orders at max.

Retry MF Purchase

POST /v2/mf_purchases/:id/retry

curl -X POST "https://s.finprim.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/retry"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API used to retry failed order, after retrying the order will be eligible to make payment again.

Note:

Can be used only when gateway provider is RTA and order has failed due to payment failure i.e. failure_code is payment_failure

JSON Response:

{
  "object": "mf_purchase",
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "old_id": 9123,
  "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
  "folio_number": "31171511",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FE6",
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-06T15:32:52+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "retried_at": null,
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "plan": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

Mf Redemptions

Represents a mutual fund sell order. You can create a redemption order via Create Redemption order API or the redemption order can be created via a redemption plan.

Endpoints:

POST /v2/mf_redemptions
PATCH /v2/mf_redemptions
GET /v2/mf_redemptions/:id
GET /v2/mf_redemptions

MF Redemption Object

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "confirmed_at": null,
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

Attribute	Type	Comments
object	string	Value is mf_redemption. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_redemption object
old_id	integer	This id is the V1 id of this redemption object. We have provided this id for backward compatibility purposes, and you can use this id in V1 APIs. However, please use V2 object ids and V2 APIs wherever possible
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the redemption order using this id
folio_number	string	This value represents the mutual fund folio number. Using the folio number, you can determine the folio in which the investor has made the redemption.
state	string	State of the redemption order. Possible values: pending, confirmed, sumitted, successful, failed, cancelled, reversed
amount	decimal	You can create a redemption order for a particular amount or you can create a redemption order for a particular number of units. If the redemption order was created for a specific amount, the value will not be empty. It will be empty otherwise. Please note that if the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.
units	decimal	You can create a redemption order for a particular amount or you can create a redemption order for a particular number of units. If the redemption order was created to redeem a certain number of units, the value will not be empty. It will be empty otherwise. Please note that if the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.
redeemed_amount	decimal	The actual amount that was redeemed.
redeemed_units	decimal	The actual number of units that were deducted from the investors holdings after the redemption order was processed by the order gateway.
redeemed_price	decimal	The NAV at which the redemption order was processed.
scheme	string	The isin of the scheme from which the redemption has to be made.
plan	string	The V2 object id of the plan with which this rdemption is associated. This value will be available only if this redemption order is created by a plan.
scheduled_on	string	The date on which the order is scheduled for submission to the order gateway(bse or rta) for processing.
traded_on	string	The date on which the trade happened. Please note that the trade will happen after the order is submitted to the order gateway.
redemption_mode	string	Mode of redemption: normal: In this mode, FP sends orders via order gateway as it does for other types of orders. Usually, the investor will receive the redemption proceeds in the bank account after two to three working days depending on TAT for redemption proceeds defined by AMCs. You can place redemption orders for any schemes(including liquid funds) in this mode. instant: This mode is only applicable for liquid fund schemes and the investor will receive the redemption proceeds in the bank account instantly on successfully placing the redemption order. This mode is currently supported by a few AMCs as of now. Click here to know more
redemption_bank_account_number	string	This value indicates the bank account number in which the instant redemption proceeds have been deposited. This value will be null if the redemption mode is normal.
redemption_bank_account_ifsc_code	string	This value indicates the IFSC code of the bank account in which the instant redemption proceeds have been deposited. This value will be null if the redemption mode is normal.
created_at	string	The time at which the order is created
confirmed_at	string	The time at which the order is confirmed
submitted_at	string	The time at which the order is submitted to the order gateway
succeeded_at	string	The time at which the order is processed successfully
failed_at	string	The time at which the order is failed
reversed_at	string	The time at which the order is reversed
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta, ,bse
source_ref_id	string	An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application).
user_ip	string	IP address of end user who has initiated the transaction.
server_ip	string	IP address of server through which the request to create this transaction was made.
euin	string	Unique identity number of the employee / relationship manager/ sales person of the distributor who has advised or interacted with the investor in any other manner for this purchase order.
distributor_id	string	The id of the distributor/ria associated with the redemption order.
initiated_by	string	The entity/person who has initiated this redemption. Possible values: investor, distributor
initiated_via	string	The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web

Create a MF Redemption

POST /v2/mf_redemptions

Note:

When you create a mf_redemption order, the order will be in the pending state. However, the orders would get submitted to the order gateway only after you mark the order as confirmed. You can use Update mf_redemption order API to mark the order as confirmed.

An order which is in pending state will be marked as failed due to inactivity after T+1 market day post RTA order submission cut-off time, if the order is not confirmed within this duration.

curl -X POST "https://s.finprim.com/v2/mf_redemptions"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "amount": 10000,
  "scheme": "INF173K01FQ0",
  "units": null,
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "source_ref_d": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "euin": null
}

JSON Response:

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "confirmed_at": null,
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	Provide the V2 id of the investment account against which this order must be placed.
scheme	yes	string	Provide the isin of the scheme for which this order must be placed
folio_number	yes	string	Provide the folio number mapped with the investment account against which order must be placed.
amount	no	integer	Provide redemption amount in Rupees. The amount should be between min_withdrawal_amount and max_withdrawal_amount and should be a multiple of withdrawal_multiples If the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order. Note : You can use Get holdings Report API to check the maximum redeemable amount for a given folio and a scheme.
units	no	decimal	Provide the number of units that you want to redeem The units should be between min_withdrawal_units and max_withdrawal_units and should be a multiple of withdrawal_multiples_units If the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order. Note : You can use Get holdings Report API to check the maximum redeemable units for a given folio and a scheme.
user_ip	no	string	Provide IP address of the end-user.
server_ip	no	string	Provide IP address of the server through which the request to create this order is made.
source_ref_id	no	string	An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application).
euin	no	string	Provide EUIN associated with the distributor through which the order is being placed.

Update a MF Redemption

PATCH /v2/mf_redemptions

curl -X PATCH "https://s.finprim.com/v2/mf_redemptions"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "state": "confirmed"
}

JSON Response:

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "confirmed",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 Id of the redemption order
state	yes	string	New state of the redemption order. Supported values: confirmed

Fetch a MF Redemption

GET /v2/mf_redemptions/:id

curl -X GET "https://s.finprim.com/v2/mf_redemptions/mfr_15f8d86bae614801bab5accaed131abc"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a given redemption order by its V2 identifier

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 or V1 id of the redemption order.

JSON Response:

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "confirmed_at": null,
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

List all MF Redemptions

GET /v2/mf_redemptions

curl -X GET "https://s.finprim.com/v2/mf_redemptions"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch all mf_redemption orders.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_redemption",
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "distributor_id": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1"
    },
    {
      "object": "mf_redemption",
      "id": "mfr_21f8a86bae614101bab5accaed121abf",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF213K04FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "distributor_id": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "aad6ca01-a002-46ar-8e1c-ea6fe191a5de",
      "user_ip": "10.1.128.11",
      "server_ip": "122.1.9.1"
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the redemptions are made.
mf_redemption_plan	no	string	Provide a redemption plan id to fetch redemption orders that belong to a particular plan..

Note:

The response can contain 100 latest orders at max.

MF Settlement Details

New V2 APIs allow you to handle payments by yourself should you wish to do so. In such cases, you can create an order and mark the order as confirmed using the Update purchase order API. If you are handling payments by yourself, it is your responsiblity to ensure that the money collected by the investors are transffered to the respective AMCs. For every purchase order received by an AMC, payment reconciliation is done. To facilitiate this activity, we share the required reports with AMCs for the payments that we manage. If you are managing payments by yourself, you can provide us the settlement details of the transfer that you have made and we will manage the rest. A settlement object represents a payment settlement made to an AMC.

Note: At present, the facility to handle payments by yourself is available for lump sum purchases only.

Endpoints:

POST /v2/mf_settlement_details
GET /v2/mf_settlement_details/:id
GET /v2/mf_settlement_details

MF Settlement Detail Object

{
  "object": "mf_settlement_detail",
  "id": "mfsd_2d88b75041fe4dcdbac30f765336da3f",
  "mf_purchase": "mfp_116a41de7cb243ca8f5eda15c3d8300aa",
  "utr_number": "889121212",
  "bank_account_number": "18603051137433",
  "payment_type": "NETBANKING",
  "beneficiary_account_number": "1143005051340",
  "beneficiary_account_title": "AMC Mutual Fund Pool AC",
  "settlement_processed_at": "2020-04-09T12:00:09+05:30"
}

Attribute	Type	Comments
object	string	Value is mf_settlement_detail. String representing the object type. Objects of the same type share the same value
mf_purchase	string	The V2 identifier of the purchase order for which these settlement details have been provided
utr_number	string	Unique transaction reference number that can be used to identify the payment that was made to the AMC's bank account against the order
bank_account_number	string	Bank account number of the investor from which payment was made
payment_type	string	Mode of payment used by the investor to make the payment. Possible values: netbanking, nach, neft, rtgs
beneficiary_account_number	string	AMC's bank account number to which the transfer was made
beneficiary_account_title	string	AMC's bank account name
settlement_processed_at	string	Time at which the settlement is processed

Create a mf settlement detail

POST /v2/mf_settlement_details

curl -X POST "https://s.finprim.com/v2/mf_settlement_details"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_purchase": "mfp_116a41de7cb243ca8f5eda15c3d8300aa",
  "payment_type": "netbanking",
  "utr_number": "889121212",
  "bank_account_number": "18603051137433",
  "beneficiary_account_number": "1143005051340",
  "beneficiary_account_title": "AMC Mutual Fund Pool AC",
  "settlement_processed_at": "2020-04-09T12:00:09"
}

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_2d88b75041fe4dcdbac30f765336da3f",
  "mf_purchase": "mfp_116a41de7cb243ca8f5eda15c3d8300aa",
  "utr_number": "889121212",
  "bank_account_number": "18603051137433",
  "payment_type": "NETBANKING",
  "beneficiary_account_number": "1143005051340",
  "beneficiary_account_title": "AMC Mutual Fund Pool AC",
  "settlement_processed_at": "2020-04-09T12:00:09+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
mf_purchase	yes	string	Provide the V2 identifier of the purchase for which this settlement was made
payment_type	yes	string	Provide the payment mode using which the investor made the payment. Possible values: netbanking, nach, neft, rtgs
utr_number	yes	string	Provide the unique transaction reference of the transfer made to the AMC
bank_account_number	yes	string	Provide the account number of the investor's bank account from which the payment originated
beneficiary_account_number	yes	string	Provide the AMC's bank account number to which the transfer was made
beneficiary_account_title	yes	string	Provide the bank account name of the AMC's bank account to which the transfer was made
settlement_processed_at	yes	string	Provide the settlement timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format

Fetch a mf settlement detail

GET /v2/mf_settlement_details/:id

curl -X GET "https://s.finprim.com/v2/mf_settlement_details/mfsd_2d88b75041fe4dcdbac30f765336da3f"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a given settlement detail by its V2 identifier

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 id of the settlement detail.

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_2d88b75041fe4dcdbac30f765336da3f",
  "mf_purchase": "mfp_116a41de7cb243ca8f5eda15c3d8300aa",
  "utr_number": "889121212",
  "bank_account_number": "18603051137433",
  "payment_type": "NETBANKING",
  "beneficiary_account_number": "1143005051340",
  "beneficiary_account_title": "AMC Mutual Fund Pool AC",
  "settlement_processed_at": "2020-04-09T12:00:09+05:30"
}

List all mf settlement details

GET /v2/mf_settlement_details

curl -X GET "https://s.finprim.com/v2/mf_settlement_details"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API can be used to fetch a settlement detail for a given purchase order.

Query Parameters

Name	Mandatory	Type	Comments
mf_purchase	yes	string	V2 id of the purchase order.

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_2d88b75041fe4dcdbac30f765336da3f",
  "mf_purchase": "mfp_116a41de7cb243ca8f5eda15c3d8300aa",
  "utr_number": "889121212",
  "bank_account_number": "18603051137433",
  "payment_type": "NETBANKING",
  "beneficiary_account_number": "1143005051340",
  "beneficiary_account_title": "AMC Mutual Fund Pool AC",
  "settlement_processed_at": "2020-04-09T12:00:09+05:30"
}

Mf Redemption Plans

Redemption plan represents a plan defined to create redemption orders on a recurring basis. At present, you can create a redmeption plan to generate redemption orders on a monthly basis.

What is the difference between a redemption plan and a Systematic Withdrawal Plan?

A redemption plan is an FP entity. This entity allows you to define how the redemption orders must be generated on periodic basis. While registering a redemption plan with FP, you can ask FP to register the redemption plan as a Systematic Withdrawal Plan with AMCs. If not, we will not register a Systematic Withdrawal Plan and instead send normal redemption orders(not SWP installments) to RTA/BSE on a periodic basis according to the schedule of the plan. However, at present, any redemption plan defined at FP is always registered as a Systematic Withdrawal Plan with respective order gateways(RTA/BSE).

Endpoints:

POST /v2/mf_redemption_plans
PATCH /v2/mf_redemption_plans
GET /v2/mf_redemption_plans/:id
GET /v2/mf_redemption_plans

MF Redemption Plan Object

{
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

Attribute	Type	Comments
object	string	Value is mf_redemption_plan. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_redemption_plan object
state	string	State of the redemption plan. Possible values: created: The plan is created, but it is not active yet. As a user, you don't have to do anything to ensure the plan becomes active. FP will automatically handle the required actions to ensure that the plan becomes active active: Congrats! Your plan is now active and installments will be generated according to the plans schedule paused: The plan was active before. However, the plan has been put on hold temporarily, and installments will not be generated till the plan is in paused state. A paused plan can be made active again and installments will continue once the plan becomes active again. At present, you can't pause a plan cancelled: The plan has been stopped, and no installment will be generated failed: Whoops! We couldn't start a plan i.e. the plan couldn't be made active after it was created completed:The plan has completed its lifecycle, and no installments will be generated after a plan is marked as completed
installment_type	string	The value of this attribute indicates the way this redemption plan is registered with order gateways. If the value is systematic_withdrawal_installment, it means that the plan is registered as a Systematic Withdrawal Plan with RTA/BSE and every installment is considered as a systematic withdrawal installment. However, if the value is normal_redemption_installment, it means that FP will create redemption orders according to the defined schedule and send the installments as normal redemption orders to order gateways At present, only systematic_withdrawal_installment type is supported.
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the redemption order using this id
folio_number	string	Indicates the folio in which the withdrawals resulting from this plan will be made
frequency	string	Frequency of the redemption plan. Possible values: monthly
scheme	string	The isin of the scheme from which the redemption wil be made
transaction_day	integer	If the frequency is monthly, the transaction_day specifies the day of the month on which the redemptions should be made
start_date	string	The date on which the first redemption will be processed
end_date	string	This is the date on which the plan will end and no installment will be generated after this particular date
number_of_installments	integer	The values specifies the number of times the redemptions must be made
next_installment_date	string	The date on which the next installment will be processed by the order gateway
previous_installment_date	string	The date on which the previous installment was processed by the order gateway
amount	decimal	Periodic withdrawal amount
source_ref_id	string	An identifier that is unique across orders of all types(purchase_plan, redemption_plan, and switch_plan). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application)
euin	string	Unique identity number of the employee / relationship manager/ sales person of the distributor who has advised or interacted with the investor in any other manner for this redemption_plan
distributor_id	string	The id of the distributor/ria associated with the redemption plan.
created_at	string	The time at which the plan is created
activated_at	string	The time at which the plan is activated
cancelled_at	string	The time at which the plan is cancelled
completed_at	string	The time at which the plan is completed
failed_at	string	The time at which the plan is failed
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta, ,bse
user_ip	string	IP address of end user who has initiated the transaction.
server_ip	string	IP address of server through which the request to create this transaction was made.
initiated_by	string	The entity/person who has initiated this redemption. Possible values: investor, distributor
initiated_via	string	The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web

Create a MF Redemption Plan

POST /v2/mf_redemption_plans

This Endpoint lets you create a redemption plan. When a redemption plan is created, the plan will be in the created state and once the registration is successful internally, the plan moves to the active state. Once you ensure that the plan is in active state, you can fetch the first installment of the plan using API.

Examples to understand when the first redemption plan installment will get processed

Redemption Plan Registration Date	Start day	First installment date
December 2nd, 2021 (Market day)	2	Jan 2nd, 2022(Since it is a Sunday, this installment will be processed on 3rd January.)
December 2nd, 2021 (Market day)	3	December 3rd, 2021(Market day)
December 4th, 2021 (Market holiday)	5	December 5th, 2021(Since it is a Sunday, this installment will be processed on 6th December 2021.)

curl -X POST "https://s.finprim.com/v2/mf_redemption_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "amount": 10000,
  "scheme": "INF173K01FQ0",
  "frequency": "monthly",
  "transaction_day": 2,
  "number_of_installments": 5,
  "initiated_by": null,
  "initiated_via": null,
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "source_ref_d": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "euin": null
}

JSON Response:

{
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	Provide the V2 id of the investment account against which this plan must be created
scheme	yes	string	Provide the isin of the scheme from which redemptions must be made
frequency	yes	string	Provide frequency of the redemption_plan. Possible values: monthly
folio_number	yes	string	Provide the folio number of the folio from which the redemption must be made. Please note that this folio number must be mapped against the investment account associated with this redemption plan
amount	yes	integer	Provide redemption amount in Rupees. If the installment_type is systematic_withdrawal_installment the amount should be between min_swp_amount and max_swp_amount and amount should be a multiple of swp_multiples of the scheme from which redemptions must be made. Else, the amount should be between min_withdrawal_amount and max_withdrawal_amount and amount should be a multiple of withdrawal_multiples of the scheme from which redemptions must be made
transaction_day	yes	integer	Specify the day on which the redemption must be made periodically. If the frequency is monthly, every month on the given transaction_day, redemption order will be processed. Please note that if for a given month, the transaction_day falls on a market holiday, the installment will be processed on the immediate market day that comes after the transaction_day. If installment_type is systematic_withdrawal_installment the value of transaction_day must be one of the days supported by the scheme and can be found in swp_frquency_data attribute of a scheme.
number_of_installments	no	integer	Total number of redemptions to be made. You can also specify an end_date instead and no_of_installments will be calculated automatically. Irrespective of whether the no_of_installments value is explicitly specified or implicitly derived from end_date, the no_of_installments must be greater than or equal to min_swp_installments of a scheme if installment_type is systematic_withdrawal_installment. The no_of_installments must be greater than or equal to 1 if installment_type is normal_redemption_installment
end_date	no	integer	The day after which no redemptions must be made. FP calculates the no_of_installments automatically from the end_date. The date must in yyyy-mm-dd format
initiated_by	no	string	The entity/person who has initiated this redemption. Possible values: investor, distributor
initiated_via	no	string	The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web
server_ip	no	string	Provide IP address of the server through which the request to create this order is made.
source_ref_id	no	string	An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application).
euin	no	string	Provide EUIN associated with the distributor through which the oder is being placed.

Fetch a MF Redemption Plan

GET /v2/mf_redemption_plans/:id

curl -X GET "https://s.finprim.com/v2/mf_redemption_plans/mfrp_dbabb25ba34c48329dbfbeff70c846f0"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a redemption plan by its id

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	Id of the redemption plan.

JSON Response:

{
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

List all MF Redemptions Plans

GET /v2/mf_redemption_plans

curl -X GET "https://s.finprim.com/v2/mf_redemption_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch all mf_redemption plans.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2021-04-01",
      "end_date": "2021-11-01",
      "number_of_installments": 7,
      "next_installment_date": "2021-06-01",
      "previous_installment_date": "2021-05-01",
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2021-04-01T17:51:21+05:30",
      "activated_at": "2021-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    },
    {
      "object": "mf_redemption_plan",
      "id": "mfrp_1ba5b25b534c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "5234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2021-04-01",
      "end_date": "2021-11-01",
      "number_of_installments": 7,
      "next_installment_date": "2021-06-01",
      "previous_installment_date": "2021-05-01",
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2021-04-01T17:51:21+05:30",
      "activated_at": "2021-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the redemption plans are created.

Note:

The response can contain 100 latest orders at max.

MF Folios

We offer data migration facilities for AMCs using which demographic information associated with the folios can be imported and accessed via FP APIs. This section describes the data model of a folio and the way to access such information.

Endpoints:

GET /v2/folios

MF Folio Object

{
  "object": "mf_folio",
  "amc": "103",
  "number": "61576584",
  "primary_investor_pan": "EWLPS1890F",
  "secondary_investor_pan": null,
  "third_investor_pan": null,
  "holding_pattern": "single",
  "primary_investor_name": "ANANDHAN S",
  "secondary_investor_name": null,
  "third_investor_name": null,
  "primary_investor_dob": "1993-04-07",
  "secondary_investor_dob": null,
  "third_investor_dob": null,
  "primary_investor_gender": null,
  "secondary_investor_gender": null,
  "third_investor_gender": null,
  "primary_investor_tax_status": "individual",
  "primary_investor_occupation": "service",
  "guardian_name": null,
  "guardian_gender": null,
  "guardian_pan": null,
  "guardian_dob": null,
  "guardian_relationship": null,
  "nominee1": null,
  "nominee1_allocation_percentage": null,
  "nominee2": null,
  "nominee2_allocation_percentage": null,
  "nominee3": null,
  "nominee3_allocation_percentage": null,
  "payout_details": [
    {
      "scheme_code": "FADP",
      "bank_account": {
        "name": null,
        "number": "SB 8132",
        "account_type": "savings",
        "ifsc": null
      }
    }
  ],
  "contact_details": [
    {
      "address": {
        "line1": "D/O LATE SHRI SUBHASH CHANDER CHHABRA",
        "line2": "PATWARIAN WALI BABA NAMDEV NAGAR",
        "line3": "ST NO-3 NR JODIYAN CHAHIYAN",
        "city": "KOTKAPURA",
        "state": "PUNJAB",
        "postal_code": "151204",
        "country_name": null,
        "country_ansi_code": null
      },
      "email": null,
      "mobile": null,
      "type": "correspondence"
    }
  ]
}

Attribute	Type	Comments
object	string	Value is mf_folio. String representing the object type. Objects of the same type share the same value
amc	string	A unique code to identify the AMC to which this folio belongs to
number	string	Folio number
primary_investor_pan	string	PAN of the first holder
secondary_investor_pan	string	PAN of the second holder
third_investor_pan	string	PAN of the third holder
holding_pattern	string	Holding nature of the investment account Possible values: single,joint,either_or_survivor,anyone_or_survivor,first_or_survivor
primary_investor_name	string	Name of the first holder
secondary_investor_name	string	Name of the second holder
third_investor_name	string	Name of the third holder
primary_investor_dob	string	Date of birth of the first holder
secondary_investor_dob	string	Date of birth of the second holder
third_investor_dob	string	Date of birth of the third holder
primary_investor_gender	string	Gender of the first holder
secondary_investor_gender	string	Gender of the second holder
third_investor_gender	string	Gender of the third holder
primary_investor_tax_status	string	Tax status of the first holder Possible values: individual,on_behalf_of_minor,others,nri_minor_nre,nri_minor_nro,qualified_foreign_investor_individual,qualified_foreign_investor_minors
primary_investor_occupation	string	Occupation of the first holder Possible values: business, service, professional,agriculture,retired,house_wife,student,doctor,private_sector_service,public_sector_service,forex_dealer,government_service,unknown_or_not_applicable,others
guardian_name	string	Name of the guardian. Please note that guardian details will be available only if the investor is a minor investor
guardian_gender	string	Gender of the guardian. Possible values: male,female,others
guardian_pan	string	PAN number of the guardian
guardian_dob	string	Date of birth of the guardian
guardian_relationship	string	Relationship of the guardian with primary investor
nominee1	object	Nominee 1 details
nominee1_allocation_percentage	string	Nominee 1 allocation percentage
nominee2	object	Nominee 2 details
nominee2_allocation_percentage	object	Nominee 2 allocation percentage
nominee3	string	Nominee 3 details
nominee3_allocation_percentage	string	Nominee 3 allocation percentage
payout_details	list	List of bank accounts defined at scheme level. These are the bank accounts to which dividend payouts and redemption proceeds will be deposited
contact_details	list	List of contact details

Nominee Detail

Attribute	Type	Comments
name	string	Nominee name
dob	string	Date of birth of the nominee
relationship	string	Relationship of the nominee with the primary investor
guardian	string	Guardian of the nominee in cases where nominee is a minor
guardian_relationship	string	Relationship of the nominee with the guardian

Payout Detail

Attribute	Type	Comments
scheme_code	string	This is unique identifier to identify a scheme in the folio. If there are dividend payouts or redemptions against this particular scheme in the folio, amount would be deposited to the bank account configured against this particular scheme in the folio
bank_account	object	Details of the bank account configured for payout purposes

Bank_Account

Attribute	Type	Comments
name	string	Account holder's name
number	string	Bank account number
account_type	string	Bank account type Possible values: savings,current,nre,nro
ifsc	string	IFSC of the bank branch where the bank account is present

Contact Detail

Attribute	Type	Comments
address	string	Address associated with the folio
email	string	Email address of the user
mobile	string	Mobile number of the user
type	string	Type of the contact details Possible values correspondence ,permanent,overseas

Address

Attribute	Type	Comments
line1	string	Address line one
line2	string	Address line two
line3	string	Address line three
city	string	City name
state	string	State name
postal_code	string	Postal code of the address may be zipcode or pincode
country_name	string	Country name
country_ansi_code	string	ANSI code of the country

List folios

GET /v2/mf_folios

curl -X GET "https://s.finprim.com/v2/mf_folios"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch all mf_folios.

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	V2 id of the investment account
license_code	no	string	ARN or RIA code associated with the transactions in the folio

Note:

The response can contain 100 latest folios at max.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_folio",
      "amc": "103",
      "number": "61576584",
      "primary_investor_pan": "EWLPS1890F",
      "secondary_investor_pan": null,
      "third_investor_pan": null,
      "holding_pattern": "single",
      "primary_investor_name": "ANANDHAN S",
      "secondary_investor_name": null,
      "third_investor_name": null,
      "primary_investor_dob": "1993-04-07",
      "secondary_investor_dob": null,
      "third_investor_dob": null,
      "primary_investor_gender": null,
      "secondary_investor_gender": null,
      "third_investor_gender": null,
      "primary_investor_tax_status": "individual",
      "primary_investor_occupation": "service",
      "guardian_name": null,
      "guardian_gender": null,
      "guardian_pan": null,
      "guardian_dob": null,
      "guardian_relationship": null,
      "nominee1": null,
      "nominee1_allocation_percentage": null,
      "nominee2": null,
      "nominee2_allocation_percentage": null,
      "nominee3": null,
      "nominee3_allocation_percentage": null,
      "payout_details": [
        {
          "scheme_code": "FADP",
          "bank_account": {
            "name": null,
            "number": "SB 8132",
            "account_type": "savings",
            "ifsc": null
          }
        }
      ],
      "contact_details": [
        {
          "address": {
            "line1": "D/O LATE SHRI SUBHASH CHANDER CHHABRA",
            "line2": "PATWARIAN WALI BABA NAMDEV NAGAR",
            "line3": "ST NO-3 NR JODIYAN CHAHIYAN",
            "city": "KOTKAPURA",
            "state": "PUNJAB",
            "postal_code": "151204",
            "country_name": null,
            "country_ansi_code": null
          },
          "email": null,
          "mobile": null,
          "type": "correspondence"
        }
      ]
    }
  ]
}

Reports

FP Reporting framework allows users to access information in an organized tabular format. We have defined a set of standard reports all of which follow a same well defined format. Depending upon the report type, FP also allows you to apply filters on the reports to narrow down the scope of the report information. At present, the maximum number of rows in a report is limited to 2000.

Report object

Attibute	Type	Comments
object	string	The value describes the category of a report. For example, transaction_report is category of reports which are primarily based on MF transactions. There might be multiple different reports under this category.
report	hash	Meta data about the report.
data	hash	Actual report data.
filter_by	hash	Filters applied while retrieving report data.

Report attributes

Attibute	Type	Description
type	string	At present, this will be standard which means that this is a standard report which has been predefined by FP for its users.
standard.name	string	Name of the standard report.
standard.desc	string	Human readable description of the standard report.

Data attributes

You can consider data attribute as an attribute whose value is a table containing the actual report data but in json format. Rows are represented by rows and coloumns are represented by columns

Attibute	Type	Description
rows	array	Each row is an array of values. The position of the value in the array determines the column to which this value belongs to. If there are multiple rows, rows attribute will contain array of such rows.
columns	array	List of column names. The details of the columns are defined the specific reports in detail.

Filter_by attributes

Please refer to specific report types for filter options.

Transaction type wise amount summary report

This report groups the transactions by their type and provides the consolidated amount against each such transaction type.

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_type_wise_amount_summary"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_from": "2000-01-01",
    "traded_on_to": "2021-07-07"
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "transaction_type_wise_amount_summary",
      "desc": "This report exposes the sum of transaction amount per each transaction type."
    }
  },
  "data": {
    "rows": [
      [
        "redemption",
        4044374.07
      ],
      [
        "switch_out",
        6713373.75
      ],
      [
        "purchase",
        13411292.51
      ],
      [
        "transfer_in",
        42440.77
      ],
      [
        "switch_in",
        7029926.1
      ],
      [
        "dividend_payout",
        185723.7
      ],
      [
        "sip",
        2921466.03
      ]
    ],
    "columns": [
      "type",
      "value"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_from": "2000-01-01",
    "traded_on_to": "2021-07-07"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	Default value is traded_on_to - 30 days. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.

Columns

Column	Type	Description
type	string	Represents transaction type. Transaction types are: purchase, sip, redemption, transfer_in, transfer_out, dividend_reinvestment, dividend_payout, bonus, switch_in, switch_out, demat, remat, pledging, un_pledging, demat_transfer_in, demat_transfer_out Please note that purchase amount includes all purchase transactions including sip installments.
value	decimal	Transaction amount.

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Fund scheme category wise AUM summary report

This report groups provides the AUM for each fund category

POST /v2/transactions/reports/fund_scheme_category_wise_aum_summary

curl -X POST "https://s.finprim.com/v2/transactions/reports/fund_scheme_category_wise_aum_summary"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_from": "2021-06-01",
    "traded_on_to": "2021-07-07",
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "fund_scheme_category_wise_aum_summary",
      "desc": "This report exposed the total AUM at fund scheme category level."
    }
  },
  "data": {
    "rows": [
      [
        "equity",
        102767.44
      ],
      [
        "debt",
        32060.2
      ]
    ],
    "columns": [
      "fund_category",
      "value"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_from": "2021-06-01",
    "traded_on_to": "2021-07-07"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	If traded_on_from is not specified, all transactions since inception are considered. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.

Columns

Column	Type	Description
fund_category	string	Fund category. Possible values: equity debt liquid others
value	decimal	AUM for the fund_category

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Transaction list report

This report lists the transactions.

POST /v2/transactions/reports/transaction_list

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_to": "2021-08-20",
    "folio_number": "60270555"
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "transaction_list",
      "desc": "List transactions matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "60270555",
        "Sarath Sandeep",
        "INF173K01940",
        "purchase",
        3499.83,
        17.245,
        "2021-06-28",
        202.95,
        null,
        "103GFGPG",
        "GF60273155SIN825689",
        "GROWTH"
      ],
      [
        "60270555",
        "Sarath Sandeep",
        "INF173K01940",
        "purchase",
        3499.83,
        18.258,
        "2021-05-26",
        191.69,
        null,
        "103GFGPG",
        "GF60273155SIN792153",
        "GROWTH"
      ]
    ],
    "columns": [
      "folio_number",
      "primary_investor_name",
      "isin",
      "type",
      "amount",
      "units",
      "traded_on",
      "traded_at",
      "corporate_action",
      "rta_product_code",
      "rta_order_reference",
      "rta_investment_option"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_to": "2021-08-20",
    "folio_number": "60270555"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	If traded_on_from is not specified, all transactions since inception are considered. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.
primary_investor_name	No	string	Name of the primary investor. Any transactions are done by investors having names that contain primary_investor_name as a substring will be considered in this report. Name matching is case insensitive.
folio_number	No	string	Filter transactions by folio number. The folio number should match exactly as it appears against the transaction
pan_number	No	string	Pan number of the primary investor. An exact case-insensitive match must happen.

Columns

Column	Type
folio_number	string
primary_investor_name	string
isin	string
type	string
amount	decimal
units	decimal
traded_on	string
traded_at	decimal
corporate_action	string
rta_product_code	string
rta_order_reference	string
rta_investment_option	string

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Investor list report

This report lists the investors.

POST /v2/investors/reports/investor_list

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "partner" : "ARN-00341"
  }'

RESPONSE:

{
  "object": "investor_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "investor_list",
      "desc": "List of investors matching the given filters"
    }
  },
  "data": {
    "rows": [
      [
        "veena.gos@gmail.com",
        "9822222271",
        "Veena Nandlal Goswami",
        "ABBPG3634E"
      ],
      [
        "sujaydey_new@gmail.com",
        "9876789872",
        "SUJAY SARAT DEY",
        "AMMPD2369R"
      ]
    ],
    "columns": [
      "email",
      "mobile",
      "investor_name",
      "pan_number"
    ]
  },
  "filter_by": {
    "partner": "ARN-00341"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	Yes	string	ARN code or RIA of the partner

Columns

Column	Type	Description
email	string	Email id of the investor.
mobile	string	Mobile number of the investor.
investor_name	string	Primary investor name
pan_number	string	Pan number of the primary investor.

Mf Purchase list report

This report lists mf_purchases.

POST /v2/mf_purchases/reports/mf_purchase_list

curl -X POST "https://s.finprim.com/v2/mf_purchases/reports/mf_purchase_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "states" : ["successful", "submitted"],
      "plan_old_ids" : ["1001"]
  }'

RESPONSE:

{
  "object": "mf_purchase_list",
  "report": {
    "type": "standard",
    "standard": {
      "name": "mf_purchase_list",
      "desc": "List mf_purchases matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "mf_purchase",
        "mfp_ad0145004e6949bd92ae41ecfc0ec21b",
        17276,
        "mfia_4742fd0a211b414ba0cae0f2519130f9",
        "62707385",
        "successful",
        1000,
        72.565,
        999.95,
        13.78,
        "INF173K01OW0",
        "additional_purchase",
        "mfpp_c470ab238bcd466cb12c22493e7ad5f0",
        "2021-08-11"
      ],
      [
        "mf_purchase",
        "mfp_142201fcd67d4e4c821bd6dec4ae8c69",
        14153,
        "mfia_4742fd0a211b414ba0cae0f2519130f9",
        "62707385",
        "successful",
        1000,
        75.525,
        999.95,
        13.24,
        "INF173K01OW0",
        "additional_purchase",
        "mfpp_c470ab238bcd466cb12c22493e7ad5f0",
        "2021-07-12"
      ]
    ],
    "columns": [
      "object",
      "id",
      "old_id",
      "mf_investment_account",
      "folio_number",
      "state",
      "amount",
      "allotted_units",
      "purchased_amount",
      "purchased_price",
      "scheme",
      "type",
      "plan",
      "traded_on"
    ]
  },
  "filter_by": {
    "states": [
      "successful",
      "submitted"
    ],
    "plan_old_ids": [
      "1001"
    ]
  }
}

Filter parameters

Name	Mandatory	Type	Comments
ids	No	string[]	IDs of mf purchases.
states	No	string[]	Supportes states are pending, confirmed, submitted, successful, failed, cancelled, refunded and reversed.
plans	No	string[]	V2 id of mf purchase plans.
plan_old_ids	No	string[]	Old IDs of plans.

Columns

Column	Type
object	string
id	string
old_id	integer
mf_investment_account	string
folio_number	string
state	string
amount	decimal
allotted_units	decimal
purchased_amount	decimal
purchased_price	decimal
scheme	string
type	string
plan	string
scheduled_on	string
traded_on	string

Mf Redemption list report

This report lists mf_redemptions.

POST /v2/mf_redemptions/reports/mf_redemption_list

curl -X POST "https://s.finprim.com/v2/mf_purchases/reports/mf_redemption_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "states" : ["successful"],
    "plans" : ["mfrp_1e43165c56114f5989e94df73d28cb7d"]
  }'

RESPONSE:

{
  "object": "mf_redemption_list",
  "report": {
    "type": "standard",
    "standard": {
      "name": "mf_redemption_list",
      "desc": "List mf_redemptions matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "mf_redemption",
        "mfr_7e5419b8797a4a3e8e2e03d7c5182c99",
        18187,
        "mfia_5b67630c5d214fcd9b22c1c9b82bf5bd",
        "55719454",
        "successful",
        1500,
        14.555,
        1500.04,
        103.06,
        "INF173K01189",
        "redemption",
        "mfrp_1e43165c56114f5989e94df73d28cb7d",
        "2021-08-20",
        "2021-08-20"
      ],
      [
        "mf_redemption",
        "mfr_afa8763b85a14d87a87a156008578daf",
        18133,
        "mfia_46c668adfb214fd59edcdba3b694a35c",
        "53736674",
        "successful",
        null,
        1276.447,
        215898.27,
        169.14,
        "INF173K01155",
        "redemption",
        "mfrp_1e43165c56114f5989e94df73d28cb7d",
        "2021-08-18",
        "2021-08-18"
      ]
    ],
    "columns": [
      "object",
      "id",
      "old_id",
      "mf_investment_account",
      "folio_number",
      "state",
      "amount",
      "redeemed_units",
      "redeemed_amount",
      "redeemed_price",
      "scheme",
      "type",
      "plan",
      "scheduled_on",
      "traded_on"
    ]
  },
  "filter_by": {
    "states": [
      "successful"
    ],
    "plans": [
      "mfrp_1e43165c56114f5989e94df73d28cb7d"
    ]
  }
}

Filter parameters

Name	Mandatory	Type	Comments
ids	No	string[]	IDs of mf redemptions.
states	No	string[]	Supportes states are pending, confirmed, submitted, successful, failed, cancelled, refunded and reversed.
plans	No	string[]	V2 id of mf redemption plans.
plan_old_ids	No	string[]	Old IDs of plans.

Columns

Column	Type
object	string
id	string
old_id	integer
mf_investment_account	string
folio_number	string
state	string
amount	decimal
redeemed_units	decimal
redeemed_amount	decimal
redeemed_price	decimal
scheme	string
type	string
plan	string
scheduled_on	string
traded_on	string