Bynn Intelligence Age Verification API

openapi: 3.2.0
info:
  title: BYNN Age Verification API
  description: 'The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Use your **Private API Key**, which looks like `private_xxxxxxxxxxxxxxxxxxxxxxxx` (or `private_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx` for a sandbox key), as the username in HTTP Basic auth with an empty password, or send it as `Authorization: Bearer `. Your keys are at https://dashboard.bynn.com/integration.'
  termsOfService: https://bynn.com/terms
  contact:
    name: BYNN Development Team
    email: hello@bynn.com
    url: https://docs.bynn.com
  license:
    name: BYNN Documentation
    url: https://docs.bynn.com
  version: '1.0'
servers:
- url: https://api.bynn.com/v1
tags:
- name: age_verification
  description: Operations about age_verifications
paths:
  /age_verification/liveness:
    post:
      summary: Create - Age Verification with Liveness
      description: Age Verification with Liveness ensures the user is physically present in front of the camera by requiring real-time facial movement detection. This method prevents spoofing, deepfakes, and injection attacks by verifying biometric liveness before estimating age. It provides a significantly higher level of security compared to static selfie-based verification, making it the preferred choice for fraud prevention and regulatory compliance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postAgeVerificationLiveness'
        required: true
      security:
      - PublicKey: []
      responses:
        '201':
          description: Create - Age Verification with Liveness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_LivenessCreate'
        '400':
          description: Could not start liveness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - age_verification
      operationId: postAgeVerificationLiveness
  /age_verification/liveness/{age_verification_id}:
    get:
      summary: Finnish - Get Age Verification Liveness Result
      description: Get the result of an Age Verification Liveness session
      parameters:
      - in: path
        name: age_verification_id
        description: Age Verification ID from Livensess Age Verification call
        required: true
        schema:
          type: string
      - in: query
        name: age_verification_model
        description: Select the AI-powered age verification model trained to estimate whether a person meets or exceeds the specified age threshold. Each model is optimized to detect individuals who are likely to be at least the given age, using facial analysis and machine learning.
        required: false
        schema:
          type: string
          enum:
          - age_verification_21_years
          - age_verification_20_years
          - age_verification_19_years
          - age_verification_18_years
          - age_verification_17_years
          - age_verification_16_years
          - age_verification_15_years
          - age_verification_14_years
          - age_verification_13_years
          - age_verification_12_years
          default: age_verification_18_years
      - in: query
        name: legal_age_21
        description: Set the legal age threshold based on your jurisdiction. The default legal age is 18. If your jurisdiction requires a legal age of 21, set this to true. This is distinct from the age verification model, which determines the age threshold for verification and does not necessarily reflect the legal age requirement.
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: liveness_confidence_threshold
        description: Set liveness treshold, normally 50 is ok, for high security applications consider around 80
        required: false
        schema:
          type: number
          format: float
          default: 50
      security:
      - PrivateKey: []
      responses:
        '200':
          description: Finnish - Get Age Verification Liveness Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_AgeVerificationResult'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - age_verification
      operationId: getAgeVerificationLivenessAgeVerificationId
  /age_verification/liveness/{session_id}:
    patch:
      summary: Start - Age Verification with Liveness
      description: Age Verification with Liveness ensures the user is physically present in front of the camera by requiring real-time facial movement detection. This method prevents spoofing, deepfakes, and injection attacks by verifying biometric liveness before estimating age. It provides a significantly higher level of security compared to static selfie-based verification, making it the preferred choice for fraud prevention and regulatory compliance.
      parameters:
      - in: path
        name: session_id
        description: Session ID from Create Livensess Age Verification
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Start - Age Verification with Liveness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_LivenessStart'
        '400':
          description: Could not start liveness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '401':
          description: Session already processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - age_verification
      operationId: patchAgeVerificationLivenessSessionId
  /age_verification/liveness/{age_verification_id}/complete:
    get:
      summary: Complete - Age Verification Liveness Result
      description: Run this to complete liveness session
      parameters:
      - in: path
        name: age_verification_id
        description: Age Verification ID from Livensess Age Verification call
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Complete - Age Verification Liveness Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_LivenessCompleted'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - age_verification
      operationId: getAgeVerificationLivenessAgeVerificationIdComplete
  /age_verification/selfie:
    post:
      summary: No liveness - Age Verification with Selfie
      description: Age Verification with Selfie is a less secure method where you submit a user’s selfie to estimate their age. It does not ensure the user is physically present and does not detect deepfakes or injection attacks. This method is suitable for images where consent has been obtained but lacks liveness detection, making it vulnerable to spoofing. For higher security, we recommend using Age Verification with Liveness, which confirms real-time presence and enhances fraud prevention.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postAgeVerificationSelfie'
        required: true
      security:
      - PrivateKey: []
      responses:
        '201':
          description: No liveness - Age Verification with Selfie
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_AgeVerificationResult'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '402':
          description: insufficient_balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '481':
          description: processing_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '482':
          description: multiple_faces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '483':
          description: no_face
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '484':
          description: could_not_estimate_age
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - age_verification
      operationId: postAgeVerificationSelfie
components:
  schemas:
    postAgeVerificationLiveness:
      type: object
      properties:
        unique_id:
          type: string
          description: Unique identifier for the user in your system so you can identify the user in a webhook callback. Can be email or uuid
      required:
      - unique_id
      description: Create - Age Verification with Liveness
    Bynn_V1_Entities_BoundingBox:
      type: object
      properties:
        height:
          type: number
          format: float
          example: 0.7512
          description: Height of the bounding box as a ratio of the overall image height
        left:
          type: number
          format: float
          example: 0.2615
          description: Left coordinate of the bounding box as a ratio of overall image width
        top:
          type: number
          format: float
          example: 0.1235
          description: Top coordinate of the bounding box as a ratio of overall image height
        width:
          type: number
          format: float
          example: 0.4836
          description: Width of the bounding box as a ratio of the overall image width
      required:
      - height
      - left
      - top
      - width
    Bynn_V1_Entities_LivenessSession:
      type: object
      properties:
        session_id:
          type: string
          description: Liveness session identifier
        credentials:
          allOf:
          - $ref: '#/components/schemas/Bynn_V1_Entities_LivenessCredentials'
          description: Credentials
        server_time:
          type: integer
          format: int32
          description: Server time in milliseconds
      required:
      - session_id
      - credentials
      - server_time
    Bynn_V1_Entities_Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: validation_error
              description: Type of error
            message:
              type: string
              example: Invalid parameters
              description: Error message
            reason:
              type: string
              example: issuer_key_unavailable
              description: Machine-readable cause, where one is set
            retry_after:
              type: integer
              format: int32
              example: 60
              description: Seconds to wait before retrying
            limit:
              type: integer
              format: int32
              example: 30
              description: The limit that was exceeded
            detail:
              type: string
              description: Operator-facing detail, outside production
          required:
          - type
          - message
      required:
      - error
      description: Bynn_V1_Entities_Error model
    Bynn_V1_Entities_Liveness:
      type: object
      properties:
        status:
          type: string
          enum:
          - verified
          - not_verified
          - not_evaluated
          example: not_evaluated
          description: Indicates whether its a verified real human in front of the camera
        confidence:
          type: number
          format: float
          example: 95.4836
          description: Indicates confidence in whether its a verified real human in front of the camera. Normally around 50 is good enough for most applications. To protect against highly sofisticated deepfake or injection attacks this should be over 80-90
      required:
      - status
      - confidence
    Bynn_V1_Entities_Face:
      type: object
      properties:
        bounding_box:
          allOf:
          - $ref: '#/components/schemas/Bynn_V1_Entities_BoundingBox'
          description: The bounding box of the face in the image
        glasses:
          type: boolean
          example: true
          description: Indicates whether the person is wearing sunglasses or eyeglasses
        predicted_gender:
          type: string
          enum:
          - male
          - female
          - undetermined
          example: female
          description: Automated guess of a person’s gender based on facial analysis. This is a prediction and may not match the person’s actual gender.
      required:
      - bounding_box
      - glasses
      - predicted_gender
    postAgeVerificationSelfie:
      type: object
      properties:
        image_base64_strict:
          type: string
          description: Base64 Strict Encoded selfie image (jpg, jpeg, png)
        image_url:
          type: string
          description: URL of a selfie image (jpg, jpeg, png)
        age_verification_model:
          type: string
          description: Select the AI-powered age verification model trained to estimate whether a person meets or exceeds the specified age threshold. Each model is optimized to detect individuals who are likely to be at least the given age, using facial analysis and machine learning.
          enum:
          - age_verification_21_years
          - age_verification_20_years
          - age_verification_19_years
          - age_verification_18_years
          - age_verification_17_years
          - age_verification_16_years
          - age_verification_15_years
          - age_verification_14_years
          - age_verification_13_years
          - age_verification_12_years
          default: age_verification_18_years
        legal_age_21:
          type: boolean
          description: Set the legal age threshold based on your jurisdiction. The default legal age is 18. If your jurisdiction requires a legal age of 21, set this to true. This is distinct from the age verification model, which determines the age threshold for verification and does not necessarily reflect the legal age requirement.
          default: false
      description: No liveness - Age Verification with Selfie
    Bynn_V1_Entities_LivenessStart:
      type: object
      properties:
        age_verification_id:
          type: string
          description: Age Verification ID
        liveness_session:
          allOf:
          - $ref: '#/components/schemas/Bynn_V1_Entities_LivenessSession'
          description: Liveness session information
      required:
      - age_verification_id
      - liveness_session
      description: Bynn_V1_Entities_LivenessStart model
    Bynn_V1_Entities_LivenessCredentials:
      type: object
      properties:
        id:
          type: string
          description: Access ID
        access_key:
          type: string
          description: Access Key
        token:
          type: string
          description: Access Session Token
      required:
      - id
      - access_key
      - token
    Bynn_V1_Entities_LivenessCreate:
      type: object
      properties:
        session_id:
          type: string
          description: Liveness session identifier
      required:
      - session_id
      description: Bynn_V1_Entities_LivenessCreate model
    Bynn_V1_Entities_LivenessCompleted:
      type: object
      properties:
        verification:
          type: string
          description: 'The verification status (always "completed" if successfully completed) '
        status:
          type: string
          description: 'Liveness Status: "created","successful", "failed", "expired"'
      required:
      - verification
      - status
      description: Bynn_V1_Entities_LivenessCompleted model
    Bynn_V1_Entities_AgeVerificationResult:
      type: object
      properties:
        unique_id:
          type: string
          example: my@user.com
          description: Unique identifier for the user in your system so you can identify the user in a webhook callback. Can be email or uuid
        is_adult:
          type: boolean
          example: true
          description: Verification result indicating whether the detected face belongs to an adult based on the estimated age range. This is a prediction and may not match the person’s actual age.
        verification_status:
          type: string
          enum:
          - pass
          - underage
          - unknown
          - pending
          - error
          example: pass
          description: Verification result indicating whether the detected face passed the given model in age verification threshold.
        age_verification_model:
          type: string
          enum:
          - age_verification_21_years
          - age_verification_20_years
          - age_verification_19_years
          - age_verification_18_years
          - age_verification_17_years
          - age_verification_16_years
          - age_verification_15_years
          - age_verification_14_years
          - age_verification_13_years
          - age_verification_12_years
          example: age_verification_18_years
          description: The AI-powered age verification model used, trained to estimate whether a person meets or exceeds the specified age threshold.
        confidence:
          type: string
          enum:
          - high
          - moderate
          - low
          example: high
          description: Confidence level indicating how certain the system is about the age verification result.
        age_range:
          allOf:
          - $ref: '#/components/schemas/Bynn_V1_Entities_AgeRange'
          description: Estimated age range of the person in the image. This is a prediction and may not match the person’s actual age.
        age_estimated:
          type: integer
          format: int32
          example: 25
          description: Estimated age of person. This is a prediction and may not match the person’s actual age.
        face:
          allOf:
          - $ref: '#/components/schemas/Bynn_V1_Entities_Face'
          description: Detected face information and attributes
        liveness:
          allOf:
          - $ref: '#/components/schemas/Bynn_V1_Entities_Liveness'
          description: Liveness attributes
        image_saved:
          type: boolean
          example: false
          description: Indicates whether the image was saved for further validation
        biometrics_saved:
          type: boolean
          example: false
          description: Indicates whether the biometrics was saved for further validation
        evaluated_at:
          type: string
          example: '2025-02-23T00:31:56.076+00:00'
          description: Timestamp of when the entity was last evaluated.
        data_destroyed_at:
          type: string
          example: '2025-02-23T00:31:56.076+00:00'
          description: Timestamp of when the data is (or will be) destroyed.
      required:
      - unique_id
      - is_adult
      - verification_status
      - age_verification_model
      - confidence
      - age_range
      - age_estimated
      - face
      - liveness
      - image_saved
      - biometrics_saved
      - evaluated_at
      - data_destroyed_at
      description: Bynn_V1_Entities_AgeVerificationResult model
    Bynn_V1_Entities_AgeRange:
      type: object
      properties:
        high:
          type: integer
          format: int32
          example: 35
          description: Upper bound of the estimated age range
        low:
          type: integer
          format: int32
          example: 25
          description: Lower bound of the estimated age range
      required:
      - high
      - low
  securitySchemes:
    PrivateKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`
    PublicKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PUBLIC KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`