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

# Create ID Check

> Email a candidate a standalone ID check: a document and selfie verification with no assessment attached. Identify the candidate by candidateId or email. Each decided verification session uses one ID check credit, retries included. Send an optional Idempotency-Key header to retry safely: the same key and body replays the original check (200), a different body returns 409 `IDEMPOTENCY_KEY_REUSED`. Subscribe to the `idCheck.sent`, `idCheck.completed` and `idCheck.expired` webhooks to follow it. ID checks are enabled per organization; without them these endpoints return 404 `NOT_FOUND`. Responses never include names, dates of birth, document data or images.

**Required scope:** `id_checks:write`



## OpenAPI

````yaml https://api.ropes.ai/api/docs/openapi.json post /api/public/id-checks
openapi: 3.0.0
info:
  title: Ropes Public API
  version: 1.0.0
  description: >-
    Public API for Ropes. Authenticate using your API key in the x-api-key
    header.
servers:
  - url: https://api.ropes.ai
    description: Production server
  - url: http://localhost:3001
    description: Local development server
security: []
paths:
  /api/public/id-checks:
    post:
      tags:
        - ID Checks
      summary: Create ID Check
      description: >-
        Email a candidate a standalone ID check: a document and selfie
        verification with no assessment attached. Identify the candidate by
        candidateId or email. Each decided verification session uses one ID
        check credit, retries included. Send an optional Idempotency-Key header
        to retry safely: the same key and body replays the original check (200),
        a different body returns 409 `IDEMPOTENCY_KEY_REUSED`. Subscribe to the
        `idCheck.sent`, `idCheck.completed` and `idCheck.expired` webhooks to
        follow it. ID checks are enabled per organization; without them these
        endpoints return 404 `NOT_FOUND`. Responses never include names, dates
        of birth, document data or images.


        **Required scope:** `id_checks:write`
      parameters:
        - schema:
            type: string
            maxLength: 255
            description: Optional key for safely retrying the same request
          required: false
          description: Optional key for safely retrying the same request
          name: Idempotency-Key
          in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIdCheckRequest'
      responses:
        '200':
          description: Idempotent replay of an earlier request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheck'
        '201':
          description: ID check created and emailed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheck'
        '400':
          description: Invalid body or Idempotency-Key header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
        '402':
          description: No ID check credits left, or ID checks are not in the contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
        '403':
          description: Forbidden - API key is missing the required scope
        '404':
          description: Candidate not found, or ID checks not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
        '409':
          description: >-
            The candidate already has an open ID check, or the idempotency key
            was reused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
        '422':
          description: The candidate has no email address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
        '429':
          description: >-
            Rate limit exceeded - contact support@ropes.ai for further
            assistance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdCheckError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateIdCheckRequest:
      type: object
      properties:
        candidateId:
          type: string
          minLength: 1
          maxLength: 255
          description: The candidate to verify. Send this or email, not both.
        email:
          type: string
          maxLength: 320
          format: email
          description: >-
            The candidate's email. Resolves to your most recently created
            candidate with that email.
        expirationDays:
          type: integer
          minimum: 1
          maximum: 30
          description: Days until the check expires (default 30).
        maxRetries:
          type: integer
          minimum: 0
          maximum: 3
          description: >-
            Guided retries after a recoverable decline (default 3, so 4
            attempts).
        startScoutIfNone:
          type: boolean
          description: >-
            Start a first Scout run on completion when the candidate has none.
            Defaults to the organization's setting.
        inviteEmailLocale:
          type: string
          enum:
            - en
            - fr
          description: Language of the invite and reminder emails (default en).
        metadata:
          type: object
          additionalProperties:
            type: string
            maxLength: 500
          description: >-
            Your own key-value pairs, returned as sent. At most 20 keys; values
            up to 500 chars.
      additionalProperties: false
    IdCheck:
      type: object
      properties:
        id:
          type: string
          description: The ID check identifier.
        candidateId:
          type: string
        status:
          type: string
          enum:
            - sent
            - in_progress
            - processing
            - verified
            - failed
            - expired
            - canceled
          description: >-
            sent: emailed, not started. in_progress: the candidate is verifying
            or retrying. processing: awaiting the decision. verified, failed,
            expired and canceled are final.
        failure:
          type: object
          nullable: true
          properties:
            code:
              type: string
              enum:
                - document_expired
                - document_unsupported
                - face_mismatch
                - document_tampered
                - consent_declined
                - other
            reason:
              type: string
              description: Plain-language explanation of the code.
          required:
            - code
            - reason
          description: Why the check or attempt failed. Null unless it failed.
        attemptCount:
          type: integer
          description: Decided verification sessions. Each one is billed.
        maxRetries:
          type: integer
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/IdCheckAttempt'
          description: Verification sessions, oldest first.
        continuity:
          type: object
          nullable: true
          properties:
            verdict:
              type: string
              enum:
                - match
                - mismatch
                - inconclusive
                - not_evaluated
            referenceIsThisCheck:
              type: boolean
              description: True when this check's verified selfie is the reference face.
          required:
            - verdict
            - referenceIsThisCheck
          description: >-
            Face continuity across the candidate's screens, from their latest
            Scout run. Null until Scout has run.
        metadata:
          type: object
          additionalProperties:
            type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        completedAt:
          type: string
          nullable: true
          format: date-time
      required:
        - id
        - candidateId
        - status
        - failure
        - attemptCount
        - maxRetries
        - attempts
        - continuity
        - metadata
        - createdAt
        - expiresAt
        - completedAt
    IdCheckError:
      type: object
      properties:
        errorCode:
          type: string
          description: >-
            Machine-readable code: INVALID_REQUEST, INVALID_IDEMPOTENCY_KEY,
            NOT_FOUND, CANDIDATE_NOT_FOUND, CREDIT_LIMIT_REACHED,
            OPEN_ID_CHECK_EXISTS, IDEMPOTENCY_KEY_REUSED,
            CANDIDATE_MISSING_EMAIL, INTERNAL_ERROR.
        message:
          type: string
        idCheckId:
          type: string
          description: The open check, for OPEN_ID_CHECK_EXISTS.
      required:
        - errorCode
        - message
    IdCheckAttempt:
      type: object
      properties:
        status:
          type: string
          enum:
            - in_progress
            - processing
            - verified
            - declined
            - failed
          description: >-
            declined: the attempt failed for a recoverable reason and the
            candidate may retry. failed: it ended the check.
        failure:
          type: object
          nullable: true
          properties:
            code:
              type: string
              enum:
                - document_expired
                - document_unsupported
                - face_mismatch
                - document_tampered
                - consent_declined
                - other
            reason:
              type: string
              description: Plain-language explanation of the code.
          required:
            - code
            - reason
          description: Why the check or attempt failed. Null unless it failed.
        startedAt:
          type: string
          nullable: true
          format: date-time
        submittedAt:
          type: string
          nullable: true
          format: date-time
        decidedAt:
          type: string
          nullable: true
          format: date-time
      required:
        - status
        - failure
        - startedAt
        - submittedAt
        - decidedAt
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Each key carries scopes chosen when it is created: `candidates:read`,
        `candidates:write`, `assessments:read`, `assessments:write`,
        `problems:read`, `problems:write`, `results:read`, `id_checks:read`,
        `id_checks:write`. Keys created before scopes existed have full access.
        A request with a key that lacks an operation's scope returns 403 naming
        the missing scope.

````

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