Gridlines Liveness API

openapi: 3.2.0
info:
  title: Check Liveness API
  version: '1.0'
  description: 'Face liveness check identifies that your user is genuine and live by asking them to click a simple selfie. Build a workflow that cannot be fooled by masks, printed images or screens with our face liveness API without adding any extra steps to your onboarding flows.


    To get the highest accuracy out of liveness API, we suggest the following guidelines to be followed while capturing an image.


    1) Ensure that the image is captured in a well-lit environment, with the subject''s face clearly visible to the camera. Excessive darkness or brightness on the face may raise the BPCER (Biometric Presentation Classification Error Rate).

    2) The face should be positioned straight and not tilted.Ensure that the eyes are open.

    3) The detected face should have a minimum size of 224X224 pixels, and the distance between the eyes should be at least 100 pixels.

    4) Be cautious of motion blur, as it can potentially increase the BPCER.

    5) Before conducting a Liveness Check, any obstructions on the face such as glasses or masks should be removed.

    6) The detected face should occupy a minimum of 20% of the total image area.

    7) When taking the image, use a selfie or portrait mode.

    8) Avoiding image compression is highly recommended.'
  contact:
    name: OnGrid
    url: ongrid.in
    email: contact@ongrid.in
servers:
- url: https://api.gridlines.io
  description: Production
security:
- X-API-Key: []
tags:
- name: Liveness
paths:
  /liveness/passive-check:
    parameters: []
    post:
      summary: Passive Liveness Check
      operationId: post-liveness-passive-check
      responses:
        '200':
          description: User Created
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    request_id: a0d8e11e-a10c-4170-826d-0837ce6c833a
                    transaction_id: 371cccc9-8922-4ab3-ae5e-59cd73599f86
                    status: 200
                    data:
                      code: '1000'
                      message: Live.
                      confidence: 0.6689565181732178
                    timestamp: 1744343103514
                    path: /liveness/passive-check
                required:
                - request_id
                - transaction_id
                - status
                - timestamp
                - path
                properties:
                  request_id:
                    type: string
                  transaction_id:
                    type: string
                  reference_id:
                    type: string
                    x-stoplight:
                      id: efsmcbd5fy7ng
                  status:
                    type: integer
                  data:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      confidence:
                        type: number
                  timestamp:
                    type: integer
                  path:
                    type: string
              examples:
                '1000':
                  value:
                    request_id: a0d8e11e-a10c-4170-826d-0837ce6c833a
                    transaction_id: 371cccc9-8922-4ab3-ae5e-59cd73599f86
                    status: 200
                    data:
                      code: '1000'
                      message: Live.
                      confidence: 0.6689565181732178
                    timestamp: 1744343103514
                    path: /liveness/passive-check
                '1001':
                  value:
                    request_id: 2c0016e0-86e7-4cbb-8105-a31b6dff8cfb
                    transaction_id: 69ac638a-e8a1-4738-be30-5bb35e9b630c
                    status: 200
                    data:
                      code: '1001'
                      message: Not Live.
                      confidence: 4.1980797504947986e-07
                    timestamp: 1744343259258
                    path: /liveness/passive-check
        '400':
          description: Missing Required Information
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    request_id: d3ab5949-8836-474f-a518-d4805f1835f8
                    transaction_id: 0bc3881e-2d49-4202-b781-f0c49a7e5097
                    status: 400
                    error:
                      code: BAD_REQUEST
                      message: Bad request.
                      type: https://docs.gridlines.io/#:~:text=Consent%20not%20provided.-,400,-BAD_REQUEST
                      metadata:
                        fields:
                        - field: base64_data
                          message: 'Unsupported file format. Supported formats are: .png, .jpg, .jpeg.'
                    timestamp: 1744343365136
                    path: /liveness/passive-check
                required:
                - request_id
                - transaction_id
                - status
                - timestamp
                - path
                properties:
                  request_id:
                    type: string
                  transaction_id:
                    type: string
                  reference_id:
                    type: string
                    x-stoplight:
                      id: op5hga5jcorod
                  status:
                    type: integer
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      type:
                        type: string
                      metadata:
                        type: object
                        properties:
                          fields:
                            type: array
                            items:
                              type: object
                              properties:
                                field:
                                  type: string
                                message:
                                  type: string
                  timestamp:
                    type: integer
                  path:
                    type: string
              examples:
                Unsupported file format:
                  value:
                    request_id: d3ab5949-8836-474f-a518-d4805f1835f8
                    transaction_id: 0bc3881e-2d49-4202-b781-f0c49a7e5097
                    status: 400
                    error:
                      code: BAD_REQUEST
                      message: Bad request.
                      type: https://docs.gridlines.io/#:~:text=Consent%20not%20provided.-,400,-BAD_REQUEST
                      metadata:
                        fields:
                        - field: base64_data
                          message: 'Unsupported file format. Supported formats are: .png, .jpg, .jpeg.'
                    timestamp: 1744343365136
                    path: /liveness/passive-check
                File size exceeded:
                  value:
                    request_id: 3ff2a721-825a-4959-9039-0adb9d213823
                    transaction_id: eee5be2b-e58f-488d-a866-712396710f96
                    status: 400
                    error:
                      code: BAD_REQUEST
                      message: Bad request.
                      type: https://docs.gridlines.io/#:~:text=Consent%20not%20provided.-,400,-BAD_REQUEST
                      metadata:
                        fields:
                        - field: base64_data
                          message: 'File size is more than the supported limit. Permitted Size: 3MB'
                    timestamp: 1744343470631
                    path: /liveness/passive-check
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples:
                Example 1:
                  file_url: https://livenesstesting.s3.ap-south-1.amazonaws.com/AMJFRB.png
                  base64_code: ''
                  consent: Y
              properties:
                file_url:
                  type: string
                base64_data:
                  type: string
                  x-stoplight:
                    id: 5bk5ch3uchfho
                consent:
                  enum:
                  - Y
                  - N
                  description: The consent of the client should also be provided as a string, "Y" for an YES and "N" for NO.
              required:
              - consent
          application/xml:
            schema:
              type: object
              properties: {}
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  x-stoplight:
                    id: cu6bj6s9rv2oo
                  description: 'The provided file should not be more than 3 MB and only PNG, JPEG and JPG images are allowed. '
                consent:
                  x-stoplight:
                    id: kclwyrfmj6vgu
                  enum:
                  - Y
                  - N
                  description: The consent of the client should also be provided as a string, "Y" for an YES and "N" for NO.
          text/html:
            schema:
              type: object
              properties: {}
          text/plain:
            schema:
              type: object
              properties: {}
          application/EDI-X12:
            schema:
              type: object
              properties: {}
          application/EDIFACT:
            schema:
              type: object
              properties: {}
          application/atom+xml:
            schema:
              type: object
              properties: {}
          application/font-woff:
            schema:
              type: object
              properties: {}
          application/gzip:
            schema:
              type: object
              properties: {}
          application/javascript:
            schema:
              type: object
              properties: {}
          application/octet-stream:
            schema:
              type: object
              properties: {}
          application/ogg:
            schema:
              type: object
              properties: {}
          application/pdf:
            schema:
              type: object
              properties: {}
        description: Please utilize the multipart/form-data request body format when transmitting the multipart file.
      description: 'This API takes individual''s face as input and provides a confidence score for determining whether the image is real or fake. If the confidence score is < 0.5, the image is determined to be fake (for example, captured from a screen or print, or if the user is wearing a printed mask); otherwise, it is considered real. Clients can use the confidence score to determine their own threshold depending on the quality of images in their sample set. The default threshold of 0.5 is only suggestive.


        We offer three distinct operational approaches:

        1) Use a file directly along with consent.

        2) Use a base64 code along with consent.

        3) Use a file URL along with consent.


        The choice must be between a file, base64 code or a file URL.


        Response Codes:


        | Sl | Status | Code | Description

        | ---- | -------|-------------------| -------------

        | 1 | 200 | 1000 | Live.

        | 2 | 200 | 1001 | Not Live.

        | 3 | 400 | MULTIPLE_FACES_FOUND| Multiple faces found in the image.

        | 4 | 400 | NO_FACE_FOUND| No face found in the image.

        | 5 | 400 | INVALID_IMAGE| Invalid image.

        | 6 | 400 | BAD_REQUEST | Unsupported file format. Supported formats are: .png, .jpg, .jpeg.

        | 7 | 400 | BAD_REQUEST |File size is more than the supported limit. Permitted Size: 3MB'
      x-stoplight:
        id: 2vm7au964vfl8
      security:
      - X-API-Key: []
      parameters:
      - schema:
          type: string
        in: header
        name: X-Auth-Type
        description: API-Key
        required: true
      - schema:
          type: string
        in: header
        name: X-Reference-ID
        description: Reference ID
      x-internal: false
      tags:
      - Liveness
components:
  securitySchemes:
    X-API-Key:
      type: apiKey
      in: header
      name: X-API-Key
x-stoplight:
  id: ykxud9qkbjgjo
x-internal: false