> ## Documentation Index > Fetch the complete documentation index at: https://docs.yorlet.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a verification session ## OpenAPI ````yaml openapi-guardrails.json POST /v1/verification_sessions openapi: 3.1.0 info: title: Yorlet Guardrails API description: Guardrails APIs including verification sessions. version: 1.0.0 servers: - url: https://api.yorlet.com description: Production - url: https://api.yorlet.io description: Sandbox security: [] paths: /v1/verification_sessions: post: tags: - Verification Sessions summary: Create a verification session operationId: verification_sessions_create requestBody: content: application/json: schema: type: object properties: metadata: type: - object - 'null' additionalProperties: type: string description: Set of key-value pairs that you can attach to the object. client_reference_id: type: string description: >- A client reference identifier to attach to the verification session. options: type: object properties: identity: type: object properties: allowed_types: type: array items: type: string enum: - driving_licence - id_card - passport description: >- The types of identity documents accepted for verification. required: - allowed_types description: Options for the identity verification check. income: type: object properties: affordability_check: type: object properties: amount: type: number description: >- The amount to assess affordability against, in the smallest currency unit. interval: type: string enum: - month - week description: The interval used for the affordability check. inverval_count: type: number description: >- The number of intervals used for the affordability check. required: - amount - interval - inverval_count description: >- Parameters to perform an affordability check during income verification. require_income_reference: type: boolean description: >- Whether the verification requires an income reference. description: Options for the income verification check. monitor: type: object properties: continuous_screening: type: boolean description: >- Whether continuous screening is enabled for the monitor check. description: Options for the monitor verification check. description: Options to apply to the verification session. provided_details: type: object properties: dob: type: - object - 'null' properties: day: type: - integer - 'null' minimum: 1 maximum: 31 month: type: - integer - 'null' minimum: 1 maximum: 12 year: type: - integer - 'null' minimum: 1900 maximum: 9999 required: - day - month - year description: The provided date of birth for the individual. email: type: - string - 'null' format: email description: The provided email address for the individual. first_name: type: - string - 'null' description: The provided first name for the individual. last_name: type: - string - 'null' description: The provided last name for the individual. phone: type: - string - 'null' description: The provided phone number for the individual. description: Details about the individual provided at session creation. related_customer: type: string description: The ID of the customer related to this verification session. related_owner_person: type: string description: >- The ID of the owner person related to this verification session. return_url: type: string format: uri description: >- The URL the user will be redirected to after completing verification. send_email: type: boolean default: false description: Whether to send a verification email to the individual. types: type: array items: type: string enum: - credit_check - income - identity - right_to_rent description: The verifications to include in this session. required: - types responses: '200': description: Returns the verification session object if the request succeeded. content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the object. created: type: number description: >- Time at which the object was created. Measured in seconds since the Unix epoch. account: type: string description: >- The account that the object belongs to. Only returned if the request is made with a valid Yorlet-Context header. deleted: type: boolean default: false description: Only returned if the object has been deleted. object: type: string enum: - verification_session completed_at: type: - integer - 'null' description: The time at which the verification session was completed. credit_check: type: - object - 'null' properties: next_action: type: - object - 'null' properties: type: type: string enum: - pending_identity - collect_identity - collect_previous_addresses description: >- The next action required to progress the credit check. required: - type description: The next action required to progress the credit check. status: type: - string - 'null' description: The status of the credit check. required: - next_action - status description: >- Credit check details, when the session includes a credit check. identity: type: - object - 'null' properties: last_error: type: - object - 'null' properties: code: type: string description: A machine-readable code identifying the error. reason: type: string description: A human-readable reason describing the error. required: - code - reason description: >- The last error encountered during identity verification. next_action: type: - object - 'null' properties: use_yorlet_sdk: type: object properties: client_secret: type: string description: >- The client secret used to authenticate the Yorlet SDK. required: - client_secret description: >- Parameters required to launch the Yorlet identity verification SDK. type: type: string enum: - use_yorlet_sdk - pending_identity - collect_identity - collect_previous_addresses description: >- The next action required to progress identity verification. required: - type description: >- The next action required to progress identity verification. status: type: - string - 'null' description: The status of identity verification. required: - last_error - next_action - status description: >- Identity verification details, when the session includes identity verification. income: type: - object - 'null' properties: next_action: type: - object - 'null' properties: type: type: string enum: - pending_income - collect_source - request_token description: >- The next action required to progress income verification. required: - type description: >- The next action required to progress income verification. status: type: - string - 'null' description: The status of income verification. required: - next_action - status description: >- Income verification details, when the session includes income verification. manually_reviewed: type: boolean default: false description: Whether the verification session was manually reviewed. monitor: type: - object - 'null' properties: next_action: type: - object - 'null' properties: type: type: string enum: - pending_identity description: >- The next action required to progress monitor verification. required: - type description: >- The next action required to progress monitor verification. status: type: - string - 'null' enum: - processing - verified - unverified - requires_review - null description: The status of monitor verification. required: - next_action - status description: >- Monitor verification details, when the session includes monitor verification. options: type: - object - 'null' properties: identity: type: object properties: allowed_types: type: array items: type: string enum: - driving_licence - id_card - passport description: >- The types of identity documents accepted for verification. required: - allowed_types description: Options for the identity verification check. income: type: object properties: affordability_check: type: object properties: amount: type: number description: >- The amount to assess affordability against, in the smallest currency unit. interval: type: string enum: - month - week description: The interval used for the affordability check. inverval_count: type: number description: >- The number of intervals used for the affordability check. required: - amount - interval - inverval_count description: >- Parameters to perform an affordability check during income verification. require_income_reference: type: boolean description: >- Whether the verification requires an income reference. description: Options for the income verification check. monitor: type: object properties: continuous_screening: type: boolean description: >- Whether continuous screening is enabled for the monitor check. description: Options for the monitor verification check. description: Options applied to the verification session. provided_details: type: - object - 'null' properties: dob: type: - object - 'null' properties: day: type: - integer - 'null' minimum: 1 maximum: 31 month: type: - integer - 'null' minimum: 1 maximum: 12 year: type: - integer - 'null' minimum: 1900 maximum: 9999 required: - day - month - year description: The provided date of birth for the individual. first_name: type: - string - 'null' description: The provided first name for the individual. email: type: - string - 'null' format: email description: The provided email address for the individual. last_name: type: - string - 'null' description: The provided last name for the individual. phone: type: - string - 'null' description: The provided phone number for the individual. required: - dob - first_name - email - last_name - phone description: >- Details provided by the individual at the start of the verification session. requirements: type: - object - 'null' properties: completed: type: array items: type: string enum: - credit_check - identity - income - right_to_rent description: The requirements that have been completed. currently_due: type: array items: type: string enum: - credit_check - identity - income - right_to_rent - email - phone - tos description: >- The requirements currently due to complete the verification session. required: - completed - currently_due description: Requirements for completing the verification session. return_url: type: - string - 'null' description: >- The URL the user will be redirected to after completing verification. right_to_rent: type: - object - 'null' properties: next_action: type: - object - 'null' properties: dob_required: type: boolean description: >- Whether the date of birth is required to progress the next action. type: type: string enum: - pending_identity - collect_source - electronic_travel_authorisation - share_code description: >- The next action required to progress right-to-rent verification. required: - type description: >- The next action required to progress right-to-rent verification. status: type: - string - 'null' enum: - requires_input - processing - verified - unverified - requires_review - null description: The status of right-to-rent verification. type: type: - string - 'null' enum: - gb_resident - ie_resident - share_code - electronic_travel_authorisation - null description: >- The type of right-to-rent check that applies to this individual. required: - next_action - status - type description: >- Right-to-rent verification details, when the session includes a right-to-rent check. status: type: string enum: - pending - complete - canceled description: The status of the verification session. types: type: array items: type: string enum: - identity - right_to_rent - income - credit_check - monitor description: The verifications included in this session. url: type: - string - 'null' description: >- The hosted URL the user can visit to complete verification. verified_outputs: type: - object - 'null' properties: affordability: type: - object - 'null' properties: cost_to_income_ratio: type: number description: >- The verified cost to income ratio for the individual. required: - cost_to_income_ratio description: Affordability outputs derived from verified income. first_name: type: - string - 'null' description: The verified first name of the individual. last_name: type: - string - 'null' description: The verified last name of the individual. required: - affordability - first_name - last_name description: Verified outputs available once verification is complete. verification_report: anyOf: - type: object properties: id: type: string description: Unique identifier for the object. created: type: number description: >- Time at which the object was created. Measured in seconds since the Unix epoch. account: type: string description: >- The account that the object belongs to. Only returned if the request is made with a valid Yorlet-Context header. deleted: type: boolean default: false description: Only returned if the object has been deleted. object: type: string enum: - verification_report identity: type: - object - 'null' properties: dob: type: - object - 'null' properties: day: type: - integer - 'null' minimum: 1 maximum: 31 month: type: - integer - 'null' minimum: 1 maximum: 12 year: type: - integer - 'null' minimum: 1900 maximum: 9999 required: - day - month - year description: The verified date of birth for the individual. expiration_date: type: - integer - 'null' description: >- The expiration date of the verified identity document. first_name: type: - string - 'null' description: The verified first name of the individual. issuing_country: type: - string - 'null' description: The country that issued the identity document. last_name: type: - string - 'null' description: The verified last name of the individual. status: type: string enum: - unverified - verified - failed description: The status of the identity verification. type: type: - string - 'null' description: >- The type of identity document that was verified. required: - dob - expiration_date - first_name - issuing_country - last_name - status - type description: Identity verification outputs. income: type: - object - 'null' properties: affordability: type: - object - 'null' properties: cost_to_income_ratio: type: number description: >- The verified cost to income ratio for the individual. required: - cost_to_income_ratio description: >- Affordability outputs derived from verified income. status: type: string enum: - unverified - verified - failed description: The status of income verification. type: type: - string - 'null' enum: - permanent_employment - self_employed - savings - student - benefits - pension - null description: The type of income source that was verified. verification: type: object properties: bank_account: type: - object - 'null' properties: items: type: array items: type: object properties: bank_name: type: string description: >- The name of the bank the account is held at. income_sources: type: array items: type: object properties: category: type: - string - 'null' description: The category of the income source. description: type: - string - 'null' description: A description of the income source. total: type: number description: >- The total amount, in the smallest currency unit, attributed to this income source. required: - category - description - total description: >- Income sources detected on the bank account. required: - bank_name - income_sources description: >- Individual bank accounts assessed for income verification. sources: type: number description: >- The total number of income sources detected across the bank accounts. total_monthly: type: number description: >- The total verified monthly income, in the smallest currency unit. total_yearly: type: number description: >- The total verified yearly income, in the smallest currency unit. required: - items - sources - total_monthly - total_yearly description: >- Bank-account-based income verification outputs. document: type: - object - 'null' properties: items: type: array items: type: object properties: employer_name: type: - string - 'null' description: >- The name of the employer listed on the document. employee_name: type: - string - 'null' description: >- The name of the employee listed on the document. pay_stubs: type: array items: type: object properties: gross_earnings: type: number description: >- The gross earnings on the pay stub, in the smallest currency unit. net_pay: type: number description: >- The net pay on the pay stub, in the smallest currency unit. pay_date: type: - integer - 'null' description: The pay date for the pay stub. pay_frequency: type: - string - 'null' description: >- The pay frequency reported on the pay stub. required: - gross_earnings - net_pay - pay_date - pay_frequency description: Pay stubs extracted from the document. required: - employer_name - employee_name - pay_stubs description: >- Documents provided for income verification. total_monthly: type: number description: >- The total verified monthly income, in the smallest currency unit. total_yearly: type: number description: >- The total verified yearly income, in the smallest currency unit. required: - items - total_monthly - total_yearly description: >- Document-based income verification outputs. type: type: - string - 'null' enum: - bank_account - document - null description: The method used to verify income. required: - bank_account - document - type description: >- Details about the verification method used for income. required: - affordability - status - type - verification description: Income verification outputs. right_to_rent: type: - object - 'null' properties: dob: type: - object - 'null' properties: day: type: - integer - 'null' minimum: 1 maximum: 31 month: type: - integer - 'null' minimum: 1 maximum: 12 year: type: - integer - 'null' minimum: 1900 maximum: 9999 required: - day - month - year description: >- The date of birth used for right-to-rent verification. dob_verification: type: - string - 'null' enum: - verified - self_declared - null description: >- Whether the date of birth was verified or self-declared. share_code: type: - string - 'null' description: >- The right-to-rent share code provided by the individual. status: type: string enum: - unverified - verified - failed description: The status of right-to-rent verification. type: type: string enum: - gb_resident - ie_resident - share_code - electronic_travel_authorisation description: >- The type of right-to-rent check that was performed. required: - dob - dob_verification - share_code - status - type description: Right-to-rent verification outputs. status: type: string enum: - unverified - verified description: The overall status of the verification report. types: type: array items: type: string enum: - identity - right_to_rent - income - credit_check description: The verifications included in the report. verification_session: type: string description: >- The ID of the verification session this report belongs to. required: - id - created - object - identity - income - right_to_rent - status - types - verification_session - type: string - type: 'null' description: >- The verification report produced for this session, when available. required: - id - created - object - completed_at - credit_check - identity - income - monitor - options - provided_details - requirements - return_url - right_to_rent - status - types - url - verified_outputs - verification_report security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API Key authentication. Use "Bearer YOUR_API_KEY". ````