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

# Start verifying a person

> Checks the BVN and sends a code to the phone on its record. Call this from your server, never from an app or browser. If this externalUserId is already verified with the same BVN, the customerId comes straight back and no code is sent.

Checks a BVN and sends a code to the phone on its record. Call it from your
server. See [Verifying your users](https://docs.paj.cash/concepts/kyc.md) for the whole flow.

Sending `consentVersion` is your statement that the person saw that consent text
and agreed to it.

If this `externalUserId` is already linked to the same BVN, you get the existing
`customerId` straight back and no code is sent. If it's linked to a different BVN,
the response is `409`.


## OpenAPI

````yaml POST /pub/v2/kyc/sessions
openapi: 3.0.0
info:
  title: Paj Public API
  description: >-
    Programmatic access to Paj's on/off ramp. Register a Nigerian bank account,
    get

    the on-chain address that pays it, create offramp orders for a specific
    amount,

    and read the live conversion rates.


    Every request must carry an `x-api-key` header. Keys are scoped to a
    business,

    and the rates you receive already have that business's fee applied.
  version: 2.0.0
  contact: {}
servers:
  - url: https://api.paj.cash
    description: Production
security: []
tags: []
paths:
  /pub/v2/kyc/sessions:
    post:
      tags:
        - Pub V2
      summary: Start verifying a person
      description: >-
        Checks the BVN and sends a code to the phone on its record. Call this
        from your server, never from an app or browser. If this externalUserId
        is already verified with the same BVN, the customerId comes straight
        back and no code is sent.
      operationId: PubV2Controller_createKycSession
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKycSessionDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycSessionResDto'
        '401':
          description: Missing or invalid API key (x-api-key header)
        '403':
          description: KYC is not enabled for this business
        '409':
          description: This externalUserId is linked to a different person
        '429':
          description: A daily limit was reached, or a code was just sent
      security:
        - x-api-key: []
components:
  schemas:
    CreateKycSessionDto:
      type: object
      properties:
        externalUserId:
          type: string
          description: Your own ID for this person. Paj never interprets it.
          example: acme-user-123
        idNumber:
          type: string
          description: >-
            The person's BVN. Send it from your server and never store or log
            it.
          example: '22222222222'
        idType:
          type: string
          enum:
            - BVN
          example: BVN
        country:
          type: string
          enum:
            - NG
          example: NG
        consentVersion:
          type: string
          description: >-
            The version of the consent text the person agreed to, from `GET
            /pub/v2/kyc/consent`. Sending it is your statement that they saw
            that text and agreed.
          example: v1
      required:
        - externalUserId
        - idNumber
        - idType
        - country
        - consentVersion
    KycSessionResDto:
      type: object
      properties:
        sessionId:
          type: string
          description: >-
            Absent when this person was already verified for you, since no new
            session was needed.
          example: kys_9fa17c2e4b6d8a0c1e3f5a7b
        status:
          type: string
          enum:
            - OTP_SENT
            - VERIFIED
            - IN_REVIEW
            - DECLINED
          example: OTP_SENT
        customerId:
          type: string
          description: >-
            What to send on orders for this person. Present on `VERIFIED` and
            `IN_REVIEW`. Orders are refused until the status is `VERIFIED`.
          example: cus_8f2a6c1d9e4b7f03a5c8d2e6b1f4a790
        externalUserId:
          type: string
          example: acme-user-123
        tier:
          type: number
          description: The verification tier reached. Present on `VERIFIED`.
          example: 1
        declineCode:
          type: string
          enum:
            - ID_NOT_VERIFIED
            - ATTEMPTS_EXCEEDED
            - ALREADY_LINKED
          description: Why, in general terms. Present on `DECLINED`.
        expiresAt:
          format: date-time
          type: string
          description: When the code stops working. Present on `OTP_SENT`.
      required:
        - status
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.