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

# Start screening a customer

> Returns 202 with a pending screening, or 200 with the saved screening for a retry with the same request_key and body.



## OpenAPI

````yaml /openapi.json post /v1/screenings
openapi: 3.1.0
info:
  description: >-
    Screen a customer at account creation. See the guide for results, errors and
    versioning.
  title: Customer Screening API
  version: 1.0.0
servers:
  - url: https://api.safely.bio
security: []
paths:
  /v1/screenings:
    post:
      tags:
        - Screenings
      summary: Start screening a customer
      description: >-
        Returns 202 with a pending screening, or 200 with the saved screening
        for a retry with the same request_key and body.
      operationId: create_v1_screenings_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreeningRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screening'
          description: The saved screening for a retry
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screening'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request or unknown policy
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing, invalid or revoked key
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: No such screening for this key
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The request_key was used with a different body
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The body exceeds 64 KB
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests, or the daily screening limit is reached
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: A required service is unavailable
      security:
        - HTTPBearer: []
components:
  schemas:
    ScreeningRequest:
      additionalProperties: false
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
        policy:
          description: The screening policy agreed with you, such as basic-onboarding.
          maxLength: 100
          minLength: 1
          title: Policy
          type: string
        reference:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          description: Your own record ID, returned unchanged.
          title: Reference
        request_key:
          description: >-
            Your unique key for this request. Retrying with the same key and
            body returns the same screening.
          maxLength: 200
          minLength: 1
          title: Request Key
          type: string
        test_scenario:
          anyOf:
            - enum:
                - approve
                - review
                - deny
                - slow
                - failed
                - unknown_values
              type: string
            - type: 'null'
          description: 'Test keys only: return a fixed screening without running checks.'
          title: Test Scenario
      required:
        - request_key
        - policy
        - customer
      title: ScreeningRequest
      type: object
    Screening:
      additionalProperties: false
      properties:
        categories:
          items:
            $ref: '#/components/schemas/Category'
          title: Categories
          type: array
        completed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Completed At
        created_at:
          format: date-time
          title: Created At
          type: string
        decision:
          anyOf:
            - $ref: '#/components/schemas/RecordedDecision'
            - type: 'null'
        error:
          anyOf:
            - $ref: '#/components/schemas/ErrorBody'
            - type: 'null'
        id:
          description: Opaque identifier of up to 255 characters; do not parse it.
          title: Id
          type: string
        livemode:
          title: Livemode
          type: boolean
        object:
          const: screening
          default: screening
          title: Object
          type: string
        policy:
          title: Policy
          type: string
        recommendation:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            approve, review or deny once completed; treat unknown values as
            review.
          title: Recommendation
        reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Reference
        request_key:
          title: Request Key
          type: string
        status:
          description: pending, completed or failed; tolerate new values.
          title: Status
          type: string
        summary:
          anyOf:
            - type: string
            - type: 'null'
          description: Plain text of at most 1,000 characters.
          title: Summary
      required:
        - id
        - livemode
        - status
        - request_key
        - reference
        - policy
        - recommendation
        - categories
        - summary
        - created_at
        - completed_at
        - decision
      title: Screening
      type: object
    ErrorResponse:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
        - error
      title: ErrorResponse
      type: object
    Customer:
      additionalProperties: false
      properties:
        billing_address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
        country:
          description: ISO 3166-1 alpha-2 country code.
          pattern: ^[A-Z]{2}$
          title: Country
          type: string
        email:
          description: The person's email address.
          maxLength: 320
          pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
          title: Email
          type: string
        group:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          description: >-
            Lab, group or department. It gives context to AI research; no rule
            depends on it.
          title: Group
        name:
          description: The person's full name.
          maxLength: 500
          minLength: 1
          title: Name
          type: string
        orcid:
          anyOf:
            - maxLength: 50
              type: string
            - type: 'null'
          description: ORCID iD. It strengthens identity matching.
          title: Orcid
        organization:
          description: The organization the person says they work for.
          maxLength: 500
          minLength: 1
          title: Organization
          type: string
        shipping_address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: >-
            Address checks use this address, or the billing address when it is
            absent.
      required:
        - name
        - email
        - organization
        - country
      title: Customer
      type: object
    Category:
      additionalProperties: false
      properties:
        category:
          description: >-
            restrictions, organization, scientist or address; tolerate new
            values.
          title: Category
          type: string
        reasons:
          description: Why the result is not clear.
          items:
            $ref: '#/components/schemas/Reason'
          title: Reasons
          type: array
        result:
          description: clear, note, flag or not_checked; treat unknown values as note.
          title: Result
          type: string
      required:
        - category
        - result
        - reasons
      title: Category
      type: object
    RecordedDecision:
      additionalProperties: false
      properties:
        action:
          enum:
            - approved
            - refused
            - more_information_requested
            - reported
          title: Action
          type: string
        decided_at:
          format: date-time
          title: Decided At
          type: string
        decided_by:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          title: Decided By
        reason:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          title: Reason
      required:
        - action
        - decided_at
      title: RecordedDecision
      type: object
    ErrorBody:
      additionalProperties: false
      properties:
        code:
          title: Code
          type: string
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
        message:
          title: Message
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
      required:
        - code
        - message
      title: ErrorBody
      type: object
    Address:
      additionalProperties: false
      properties:
        city:
          maxLength: 500
          minLength: 1
          title: City
          type: string
        country:
          description: Two-letter ISO 3166-1 alpha-2 country code.
          pattern: ^[A-Z]{2}$
          title: Country
          type: string
        line1:
          maxLength: 500
          minLength: 1
          title: Line1
          type: string
        line2:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          title: Line2
        postal_code:
          anyOf:
            - maxLength: 20
              minLength: 1
              type: string
            - type: 'null'
          title: Postal Code
        region:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          title: Region
      required:
        - line1
        - city
        - country
      title: Address
      type: object
    Reason:
      additionalProperties: false
      properties:
        code:
          description: >-
            Stable reason code; tolerate new codes. Current codes:
            address_far_from_organization, address_not_confirmed,
            affiliation_not_confirmed, check_unavailable, country_risk,
            email_domain_invalid, export_control_match, input_missing,
            lookalike_domain, mail_drop, new_email_domain,
            no_life_sciences_activity, no_publications_found,
            organization_not_found, personal_email, residential_address,
            restriction_not_cleared, sanctions_match.
          title: Code
          type: string
        message:
          description: Readable explanation; wording may change.
          title: Message
          type: string
      required:
        - code
        - message
      title: Reason
      type: object
  securitySchemes:
    HTTPBearer:
      description: Send the API key as a Bearer token.
      scheme: bearer
      type: http

````

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