> ## Documentation Index
> Fetch the complete documentation index at: https://docs.konnectnxt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Financial Data Pull

> Fetches financial and bureau data for an individual using their mobile number and full name. Returns personal information, phone records, email records, identity documents, and address history sourced from the credit bureau.

**Credit usage:** 1 credit is consumed per request whenever the bureau is successfully reached — including when the bureau returns no data (`404`). No credit is consumed for `400`, `401`, `402`, `403`, or `500` responses.

Fetches financial and bureau data for an individual using their **mobile number** and **full name**. The response returns personal information, phone records, email records, identity documents, and address history sourced from the credit bureau.

**Credit usage:** 1 credit is consumed per request whenever the bureau is successfully reached — including when the bureau returns no data (`404`). No credit is consumed for `400`, `401`, `402`, `403`, or `500` responses.


## OpenAPI

````yaml POST /v2/finance/customer-data-pull
openapi: 3.0.0
info:
  title: KonnectNXT API Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://bgv.konnectnxt.com/api
    description: Production
  - url: https://testbgv.konnectnxt.com/api
    description: QA
security:
  - bearerAuth: []
paths:
  /v2/finance/customer-data-pull:
    post:
      tags:
        - Financial Verification
      summary: Customer Financial Data Pull
      description: >-
        Fetches financial and bureau data for an individual using their mobile
        number and full name. Returns personal information, phone records, email
        records, identity documents, and address history sourced from the credit
        bureau.


        **Credit usage:** 1 credit is consumed per request whenever the bureau
        is successfully reached — including when the bureau returns no data
        (`404`). No credit is consumed for `400`, `401`, `402`, `403`, or `500`
        responses.
      operationId: customerDataPull
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerDataPullRequest'
            examples:
              Example:
                summary: Customer data pull request
                value:
                  mobile_number: '9553226860'
                  full_name: Manish Gupta
                  consent_purpose: Financial data verification for background verification
      responses:
        '200':
          description: Customer financial data fetched successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/APIBaseResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/CustomerDataPullData'
                  - $ref: '#/components/schemas/Credits'
              examples:
                Success:
                  summary: Successful customer data pull
                  value:
                    status: success
                    code: 200
                    message: Financial data fetched successfully.
                    data:
                      reportOrderNumber: '2678022808'
                      personalInfo:
                        fullName: MANCHA VENKATA VENKATA SAI
                        dob: '2001-12-02'
                        gender: Male
                        totalIncome: ''
                        occupation: SALARIED
                        age: '24'
                      phoneInfo:
                        - sequence: '1'
                          reportedDate: '2026-02-15'
                          typeCode: H
                          number: '9553226860'
                        - sequence: '2'
                          reportedDate: '2026-05-15'
                          typeCode: M
                          number: '9553226860'
                      emailInfo:
                        - sequence: '1'
                          reportedDate: '2026-04-30'
                          emailAddress: VENKATASAIM16@GMAIL.COM
                      identityInfo:
                        panNumber:
                          - idNumber: NSCPS7889L
                            sequence: '1'
                        passportNumber: []
                        drivingLicense: []
                        voterId: []
                        aadhaarNumber: []
                        rationCard: []
                        otherId: []
                      addressInfo:
                        - sequence: '1'
                          address: SO VENKATESWARA RAO H NO 121277 VIRAT NA
                          state: ANDHRA PRADESH
                          type: Permanent
                          postal: '523225'
                          reportedDate: '2026-04-30'
                    credits_used: 1
                    credits_remaining: 999
        '400':
          description: Bad request due to invalid input data. No credit is consumed.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - $ref: '#/components/schemas/APIErrorData'
              examples:
                Mobile Number Missing:
                  summary: Mobile number or full name missing
                  value:
                    status: error
                    code: 400
                    message: mobile_number and full_name are required.
                    data: null
                Invalid Mobile Number:
                  summary: Invalid mobile number format
                  value:
                    status: error
                    code: 400
                    message: >-
                      Invalid mobile number. Must be 10 digits starting with 6,
                      7, 8 or 9.
                    data: null
                Identical Digits:
                  summary: All digits are identical
                  value:
                    status: error
                    code: 400
                    message: Invalid mobile number. All digits cannot be the same.
                    data: null
                Invalid Full Name:
                  summary: Invalid full name format
                  value:
                    status: error
                    code: 400
                    message: Full name can contain only letters, spaces, or dots.
                    data: null
                Consent Purpose Too Short:
                  summary: Consent purpose less than 20 characters
                  value:
                    status: error
                    code: 400
                    message: consent_purpose must be more than 20 characters.
                    data: null
                Consent Required:
                  summary: Consent not provided
                  value:
                    status: error
                    code: 400
                    message: >-
                      Consent is required to perform financial data
                      verification.
                    data: null
        '401':
          $ref: '#/components/responses/401'
        '402':
          description: Insufficient credits. No credit is consumed.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - $ref: '#/components/schemas/APIErrorData'
              examples:
                Insufficient Credits:
                  summary: Not enough credits to perform this operation
                  value:
                    status: error
                    code: 402
                    message: Insufficient credits to perform this operation.
                    data: null
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: >-
            No financial data found for the provided mobile number. **1 credit
            is charged** because the bureau was successfully reached but
            returned no data. `credits_used` and `credits_remaining` are
            included in the response body.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/APIBaseResponse'
                  - $ref: '#/components/schemas/APIErrorData'
                  - $ref: '#/components/schemas/Credits'
              examples:
                Not Found:
                  summary: No data found — 1 credit charged
                  value:
                    status: error
                    code: 404
                    message: >-
                      No response was received from the financial data service
                      for the registered mobile number.
                    data: null
                    credits_used: 1
                    credits_remaining: 998
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    CustomerDataPullRequest:
      type: object
      required:
        - mobile_number
        - full_name
      properties:
        mobile_number:
          type: string
          description: >-
            10-digit Indian mobile number starting with 6, 7, 8, or 9. All
            digits cannot be identical (e.g. 9999999999 is invalid).
          example: '9553226860'
        full_name:
          type: string
          description: >-
            Full name of the individual. Only letters, spaces, and dots are
            allowed.
          example: Manish Gupta
        consent_purpose:
          type: string
          description: >-
            Purpose for which consent is taken from the individual. If provided,
            must be more than 20 characters. Defaults to "Financial data
            verification for background verification" when not supplied.
          example: Financial data verification for background verification
        document_type:
          type: string
          description: >-
            Optional document type for an additional identity lookup (e.g. PAN,
            AADHAAR).
          example: ''
        id_value:
          type: string
          description: Optional ID value associated with the supplied document_type.
          example: ''
    APIBaseResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          $ref: '#/components/schemas/APIStatus'
        code:
          $ref: '#/components/schemas/HTTPCode'
        message:
          $ref: '#/components/schemas/APIMessage'
    CustomerDataPullData:
      type: object
      properties:
        reportOrderNumber:
          type: string
          description: Unique report order number returned by the bureau.
          example: '2678022808'
        personalInfo:
          $ref: '#/components/schemas/PersonalInfo'
        phoneInfo:
          type: array
          description: List of phone records reported to the bureau.
          items:
            $ref: '#/components/schemas/PhoneInfo'
        emailInfo:
          type: array
          description: List of email records reported to the bureau.
          items:
            $ref: '#/components/schemas/EmailInfo'
        identityInfo:
          $ref: '#/components/schemas/IdentityInfo'
        addressInfo:
          type: array
          description: List of address records reported to the bureau.
          items:
            $ref: '#/components/schemas/AddressInfo'
    Credits:
      type: object
      properties:
        credits_used:
          $ref: '#/components/schemas/CreditsUsed'
        credits_left:
          $ref: '#/components/schemas/CreditsLeft'
      required:
        - credits_used
        - credits_left
    Error:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
    APIErrorData:
      type: object
      properties:
        data:
          type: object
          nullable: true
          example: null
    APIStatus:
      type: string
      enum:
        - success
        - error
      description: Overall status of the API
    HTTPCode:
      type: integer
      description: HTTP status code
      example: 400
    APIMessage:
      type: string
      description: Description of the response or error
      example: Invalid request parameters
    PersonalInfo:
      type: object
      properties:
        fullName:
          type: string
          description: Full name of the individual as per bureau records.
          example: MANCHA VENKATA VENKATA SAI
        dob:
          type: string
          format: date
          description: Date of birth in YYYY-MM-DD format.
          example: '2001-12-02'
        gender:
          type: string
          description: Gender of the individual.
          example: Male
        totalIncome:
          type: string
          description: >-
            Total income as reported to the bureau. May be empty if not
            available.
          example: ''
        occupation:
          type: string
          description: Occupation of the individual.
          example: SALARIED
        age:
          type: string
          description: Age of the individual.
          example: '24'
    PhoneInfo:
      type: object
      properties:
        sequence:
          type: string
          description: Sequence number of the phone record.
          example: '1'
        reportedDate:
          type: string
          format: date
          description: Date the phone number was reported to the bureau.
          example: '2026-02-15'
        typeCode:
          type: string
          description: Type of phone number. H = Home, M = Mobile, T = Telephone.
          enum:
            - H
            - M
            - T
          example: M
        number:
          type: string
          description: Phone number on record.
          example: '9553226860'
    EmailInfo:
      type: object
      properties:
        sequence:
          type: string
          description: Sequence number of the email record.
          example: '1'
        reportedDate:
          type: string
          format: date
          description: Date the email was reported to the bureau.
          example: '2026-04-30'
        emailAddress:
          type: string
          description: Email address on record.
          example: VENKATASAIM16@GMAIL.COM
    IdentityInfo:
      type: object
      description: >-
        Identity documents on record, grouped by document type. Each group is an
        array and may be empty when no documents of that type are available.
      properties:
        panNumber:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
        passportNumber:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
        drivingLicense:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
        voterId:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
        aadhaarNumber:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
        rationCard:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
        otherId:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
    AddressInfo:
      type: object
      properties:
        sequence:
          type: string
          description: Sequence number of the address record.
          example: '1'
        address:
          type: string
          description: Full address as reported to the bureau.
          example: SO VENKATESWARA RAO H NO 121277 VIRAT NA
        state:
          type: string
          description: State of the address.
          example: ANDHRA PRADESH
        type:
          type: string
          description: Type of address (e.g. Primary, Permanent, Rents).
          example: Permanent
        postal:
          type: string
          description: Postal / PIN code of the address.
          example: '523225'
        reportedDate:
          type: string
          format: date
          description: Date the address was reported to the bureau.
          example: '2026-04-30'
    CreditsUsed:
      type: integer
      description: Represents the total number of credits used in this request.
      example: 3
    CreditsLeft:
      type: integer
      description: 'Represents the remaining credits available for use. '
      example: 4040
    IdentityDocument:
      type: object
      properties:
        idNumber:
          type: string
          description: Identity document number.
          example: NSCPS7889L
        sequence:
          type: string
          description: Sequence number of the identity record.
          example: '1'
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Missing Token:
              summary: Bearer token is missing or invalid.
              value:
                status: error
                code: 401
                message: Bearer token is missing or invalid.
                data: null
            Incorrect Token Format:
              summary: Token format is incorrect
              value:
                status: error
                code: 401
                message: Token format is incorrect
                data: null
            No Admin Found:
              summary: No admin found for this request
              value:
                status: error
                code: 401
                message: No admin user found for this organization
                data: null
            Invalid API Key:
              summary: Invalid API Key
              value:
                status: error
                code: 401
                message: Invalid API key (organization ID)
                data: null
            User not Found:
              summary: User not found
              value:
                status: error
                code: 401
                message: User not found.
                data: null
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Token Revoked:
              summary: Token access has been Revoked, Contact Support.
              value:
                status: error
                code: 403
                message: Token access has been Revoked, Contact Support.
                data: null
            Token Inactive:
              summary: Token is Inactive, Contact Support.
              value:
                status: error
                code: 403
                message: Token is Inactive, Contact Support.
                data: null
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Internal Server Error:
              summary: Internal Server Error.
              value:
                status: error
                code: 500
                message: Internal Server Error.
                data: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued by KonnectNXT. Pass as `Authorization: Bearer
        <your_api_key>`.

````