> ## 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.

# Employment History

> Fetches previous employment history using the candidate's mobile number.

<Warning>
  Due to EPFO restrictions, this API can only provide the candidate's **last
  employment record**. Full employment history is no longer available.
</Warning>

This API retrieves a candidate's past employment details using a valid **10-digit Indian mobile number**. When you supply the mobile number, the API fetches basic personal information—such as full name, gender, and date of birth—and returns a list of previous employers, including details like joining and exit dates, employer names, and identification numbers. Essentially, it streamlines the process of obtaining verified work history data, which can be useful for background checks and employment verification purposes.

<Note>
  You will be charged for API calls regardless of the response, including both
  `200` (successful) and `404` (not found) status codes.
</Note>


## OpenAPI

````yaml GET /verification/get-employment-history
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:
  /verification/get-employment-history:
    get:
      tags:
        - Employment Verification
      description: Fetches previous employment history using the candidate's mobile number.
      operationId: verification_get_employment_history
      parameters:
        - name: mobile
          in: query
          required: true
          schema:
            type: string
            pattern: ^[6-9]\d{9}$
            example: '9990191919'
          description: The 10-digit Indian mobile number of the candidate.
      responses:
        '200':
          description: Successful response with employment history details.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/APIBaseResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: object
                        required:
                          - case_id
                          - personal_details
                          - employment_history
                        properties:
                          case_id:
                            $ref: '#/components/schemas/CaseId'
                          personal_details:
                            type: object
                            description: Basic personal details of the candidate
                            properties:
                              user_gender:
                                type: string
                                enum:
                                  - MALE
                                  - FEMALE
                                  - OTHER
                              user_dob:
                                type: string
                                format: date
                                description: 'Date format: DD-MM-YYYY'
                                example: 23-08-1999
                              user_full_name:
                                type: string
                              user_phone_number:
                                type: string
                                description: 10-digit mobile number
                            required:
                              - user_gender
                              - user_dob
                              - user_full_name
                              - user_phone_number
                          employment_history:
                            type: array
                            description: List of previous employers.
                            items:
                              type: object
                              properties:
                                sequence_number:
                                  type: string
                                uan_number:
                                  type: string
                                date_of_exit:
                                  type: string
                                date_of_joining:
                                  type: string
                                  description: 'Date format: DD-MM-YYYY'
                                establishment_id:
                                  type: string
                                establishment_name:
                                  type: string
                                member_id:
                                  type: string
                                exit_reason:
                                  type: string
                                mobile:
                                  type: string
                                aadhaar_verification_status:
                                  type: string
                              required:
                                - sequence_number
                                - uan_number
                                - date_of_exit
                                - date_of_joining
                                - establishment_id
                                - establishment_name
                                - member_id
                                - exit_reason
                                - mobile
                                - aadhaar_verification_status
                  - $ref: '#/components/schemas/Credits'
              examples:
                Success:
                  summary: Employment history fetched successfully.
                  value:
                    status: success
                    code: 200
                    message: Data Fetched Successfully.
                    data:
                      case_id: 8a3b2d79e91c4ff1b2e97b9f2b36c123
                      personal_details:
                        user_gender: MALE
                        user_dob: 23-08-1999
                        user_full_name: John Doe
                        user_phone_number: '9101010101'
                      employment_history:
                        - sequence_number: '1'
                          uan_number: '100342762111'
                          date_of_exit: NA
                          date_of_joining: 30-03-2015
                          establishment_id: PYKRP00139620000023393
                          establishment_name: ABC Pvt Ltd
                          member_id: PBK0012345678
                          exit_reason: NA
                          mobile: NA
                          aadhaar_verification_status: ''
                    credits_used: 1
                    credits_remaining: 499
        '400':
          $ref: '#/components/responses/400_WithCredits'
          description: Bad request due to invalid or missing mobile number.
          content:
            application/json:
              examples:
                Missing Mobile:
                  summary: Mobile number missing
                  value:
                    status: error
                    code: 400
                    message: '`mobile` is required.'
                    data: null
                    credits_used: 0
                    credits_remaining: 8858
                Blank Mobile:
                  summary: Blank Mobile
                  value:
                    status: error
                    code: 400
                    message: '`mobile` can''t be blank'
                    data: null
                    credits_used: 0
                    credits_remaining: 8858
                Invalid Mobile:
                  summary: Invalid Mobile Format
                  value:
                    status: error
                    code: 400
                    message: Enter a valid 10-digit Indian mobile number.
                    data: null
                    credits_used: 0
                    credits_remaining: 8858
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: No Records Found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/APIBaseResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: object
                        required:
                          - case_id
                        properties:
                          case_id:
                            $ref: '#/components/schemas/CaseId'
                  - $ref: '#/components/schemas/Credits'
              examples:
                No records found:
                  summary: No records Found
                  value:
                    status: error
                    code: 404
                    message: No records found.
                    data:
                      case_id: 8a3b2d79e91c4ff1b2e97b9f2b36c123
                    credits_used: 2
                    credits_remaining: 499
        '500':
          $ref: '#/components/responses/500_WithCredits'
          description: Internal server error.
components:
  schemas:
    APIBaseResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          $ref: '#/components/schemas/APIStatus'
        code:
          $ref: '#/components/schemas/HTTPCode'
        message:
          $ref: '#/components/schemas/APIMessage'
    CaseId:
      required:
        - case_id
      type: string
      description: Unique Case Id for BGV
    Credits:
      type: object
      properties:
        credits_used:
          $ref: '#/components/schemas/CreditsUsed'
        credits_left:
          $ref: '#/components/schemas/CreditsLeft'
      required:
        - credits_used
        - credits_left
    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
    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
    Error:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
    APIErrorData:
      type: object
      properties:
        data:
          type: object
          nullable: true
          example: null
  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
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Credit Limit Exceed:
              summary: Credit Limit Exceeded.
              value:
                status: error
                code: 402
                message: Credit Limit Exceeded.
                data: null
            Insufficient Credits:
              summary: Insufficient credits
              value:
                status: error
                code: 402
                message: 'Insufficient credits: 2 required, 1 remaining.'
                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
    400_WithCredits:
      description: Bad Request
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
              - $ref: '#/components/schemas/Credits'
    500_WithCredits:
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
              - $ref: '#/components/schemas/Credits'
          examples:
            Internal Server Error:
              summary: Internal Server Error.
              value:
                status: error
                code: 500
                message: Internal Server Error.
                data: null
                credits_used: 3
                credits_remaining: 178
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued by KonnectNXT. Pass as `Authorization: Bearer
        <your_api_key>`.

````