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

# Verify session

> Verifies that the supplied first name, last name, and email match the
identity record (`idv_rec`) on file in the Identity Vault, and that the
identity is verified and YSWS-eligible.

The `submit_id` token is single-use and must have been authorized for the
same `idv_rec` (and program, when supplied). The token is consumed on a
successful verified response.

`idv_rec` may be passed either as `idv_rec=...&submit_id=...` or as a
combined `idv_rec=IDENTITY:SUBMIT` value.


* The `idv_rec` may be provided as a combined token in the form `IDENTITY:SUBMIT`. In that case, the portion after the colon is treated as the one-time `submit_id`.
* Alternatively, you can pass `idv_rec` and `submit_id` as separate query parameters.
* Reusing a `submit_id` results in a 410 Gone response.


## OpenAPI

````yaml GET /api/verify
openapi: 3.1.0
info:
  title: Hack Club Submit API
  description: >-
    API for identity verification and headless authorization flows. Includes
    endpoints for verifying user identities and programmatic authorization via
    popup flows.
  license:
    name: MIT
  version: 1.1.0
servers:
  - url: https://submit.hackclub.com
security: []
paths:
  /api/verify:
    get:
      tags:
        - Verification
      summary: Verify a Submit session
      description: >-
        Validates an Identity Vault record (idv_rec) against provided first/last
        name and email for a specific Submit session. A one-time OAuth-issued
        submit token is required and must match the identity.
      parameters:
        - name: idv_rec
          in: query
          required: true
          description: >-
            Identity Vault record identifier. May include a trailing
            `:SUBMIT_TOKEN` (e.g., `id_abc123:sub_456`) in which case the token
            will be extracted and used as the `submit_id`.
          schema:
            type: string
        - name: submit_id
          in: query
          required: true
          description: >-
            One-time submit token, issued via the OAuth callback. Provide this
            if it is not embedded in `idv_rec`. Missing, mismatched, or
            unauthorized tokens return 403; reuse returns 410 Gone.
          schema:
            type: string
        - name: first_name
          in: query
          required: true
          schema:
            type: string
        - name: last_name
          in: query
          required: true
          schema:
            type: string
        - name: email
          in: query
          required: true
          schema:
            type: string
            format: email
      responses:
        '200':
          description: >-
            Verification result. `verified` will be true only if first name,
            last name, and email all match the verified record. When an identity
            wasn't found upstream, the endpoint still returns 200 with
            `verified=false` and `identity_response=null`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              examples:
                verified:
                  summary: All fields match
                  value:
                    verified: true
                    identity_response:
                      id: id_123
                      verification_status: verified
                      ysws_eligible: true
                      email: user@example.com
                not_verified_mismatch:
                  summary: Identity found but provided data doesn't match
                  value:
                    verified: false
                    identity_response:
                      verification_status: verified
                      ysws_eligible: true
                      first_name: Alice
                      last_name: Smith
                      email: alice@sample.com
                ineligible:
                  summary: YSWS ineligible
                  value:
                    verified: false
                    error: YSWS programs are for individuals 18 and under only
                    identity_response:
                      verification_status: verified
                      ysws_eligible: false
                      email: user@example.com
                unknown_identity:
                  summary: Identity not found upstream
                  value:
                    verified: false
                    identity_response: null
        '400':
          description: Missing required parameters (idv_rec, first_name, last_name, email).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                verified: false
                error: >-
                  Missing required parameters: idv_rec, first_name, last_name,
                  email
                identity_response: null
        '403':
          description: >-
            Forbidden. Either the program exists but is inactive, or the submit
            token is missing/unauthorized for the given identity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                inactive_program:
                  summary: Program is inactive
                  value:
                    verified: false
                    error: Program is inactive
                    identity_response: null
                missing_token:
                  summary: Missing submit token
                  value:
                    verified: false
                    error: Submit token required
                    identity_response: null
                unauthorized_token:
                  summary: Token not authorized for identity
                  value:
                    verified: false
                    error: Submit token not authorized for this identity
                    identity_response: null
        '404':
          description: Program not found (when a program slug is provided).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                verified: false
                error: Program not found
                identity_response: null
        '410':
          description: Submit token (submit_id) already used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                verified: false
                error: Submit token already used
                identity_response: null
        '500':
          description: >-
            Internal server error (e.g., upstream fetch failure or server
            misconfiguration).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                server_config:
                  summary: Server configuration error
                  value:
                    verified: false
                    error: Server configuration error
                    identity_response: null
                fetch_failed:
                  summary: Failed to fetch user data
                  value:
                    verified: false
                    error: Failed to fetch user data
                    identity_response: null
components:
  schemas:
    VerifyResponse:
      type: object
      required:
        - verified
        - identity_response
      properties:
        verified:
          type: boolean
        identity_response:
          description: >-
            Identity fields returned. When a program is specified, fields are
            filtered by that program's allowed scopes; otherwise a minimal set
            is returned.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/IdentityResponse'
        error:
          type: string
          description: Present when an error or ineligibility occurred.
    ErrorResponse:
      type: object
      required:
        - verified
        - identity_response
        - error
      properties:
        verified:
          type: boolean
        error:
          type: string
        identity_response:
          type: 'null'
    IdentityResponse:
      type: object
      description: >-
        Normalized identity data. Fields may vary based on program scopes. The
        minimal default set includes: id, verification_status, ysws_eligible,
        email. Additional fields like slack_id can be requested via program
        scopes.
      properties:
        id:
          type: string
          description: Identity ID
        verification_status:
          type: string
          description: Verification status of the identity
          enum:
            - verified
            - pending
            - rejected
            - unverified
        ysws_eligible:
          type: boolean
          description: Whether the identity is eligible for YSWS programs (18 and under).
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        slack_id:
          type: string
          description: >-
            Slack user ID (available when slack_id scope is enabled for the
            program)
        rejection_reason:
          type: string
      additionalProperties: true

````