didit-sdk 1.0.0

data/lib/didit/resources/users.rb

@@ -0,0 +1,521 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +users+ resource.
+    class Users < Didit::Resource
+      # Batch delete users
+      #
+      # **Permanently delete** users: the user records are removed permanently. For everyday blocking prefer [Update
+      # User Status](#patch-/v3/users/-vendor_data-/update-status/) with `BLOCKED`. Select users with
+      # `vendor_data_list`, with `didit_internal_id_list`, or with both at once; or pass `delete_all: true`. This
+      # endpoint never narrows `delete_all` with filters. The Console's People filters are refused with a `400` (see
+      # the `400` response), so a narrowed intent does not turn into a full wipe. Two exceptions:
+      # `filter_has_approved_sessions` and `filter_has_declined_sessions` are not refused and not applied, so with
+      # `delete_all: true` they still delete every user; do not send them.
+      #
+      # **Biometric templates:** every image-free biometric template retained for these users after session deletion
+      # (see `/v3/biometric-templates/`) is purged before the user is deleted, so the person stops matching in
+      # duplicate detection and Face Search. If a template cannot be purged because a biometric store is unavailable,
+      # the call returns `503`, no user in the request is deleted, and repeating the request finishes the job.
+      #
+      # **Filed regulatory reports:** if the selected data is in a finalized regulatory report, the whole request is
+      # refused with `409` and nothing is deleted. The body uses `code: in_filed_report` and names each report with
+      # `uuid`, `report_number`, `report_type` and `case_uuid`. Delete the reports, then repeat the request.
+      #
+      # +POST /v3/users/delete/+
+      #
+      # @param vendor_data_list [Array<String>] Your own identifiers to delete, matched exactly as sent.
+      # @param didit_internal_id_list [Array<String>] Didit internal user IDs to delete - the `didit_internal_id`
+      #   returned by the create and get endpoints.
+      # @param delete_all [Boolean] If `true`, deletes every user in the application.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::UsersBatchDeleteResponse]
+      def batch_delete(vendor_data_list: OMIT, didit_internal_id_list: OMIT, delete_all: OMIT, request_options: nil)
+        @client.request(
+          :post,
+          "/v3/users/delete/",
+          body: {
+            "vendor_data_list" => vendor_data_list,
+            "didit_internal_id_list" => didit_internal_id_list,
+            "delete_all" => delete_all
+          },
+          response: Types::UsersBatchDeleteResponse,
+          request_options: request_options
+        )
+      end
+
+      # Create user
+      #
+      # Create a [user](/entities/users) by `vendor_data`, before or without a verification session. `vendor_data`
+      # must be unique among the application's users (a duplicate returns `400`). Not idempotent.
+      #
+      # **Contact details:** `email` and `phone_number` are stored in `metadata.contact`, and `country` in
+      # `metadata.address`. When you send `first_name` or `last_name` without `full_name`, Didit joins them into
+      # `full_name`.
+      #
+      # **Verification link:** with `send_verification_link: true`, Didit also creates a verification session for the
+      # person on `workflow_id` and emails them the link at `email`. The session runs the same checks as [Create
+      # Session](/sessions-api/create-session), such as the blocklist and your credit balance. The person and the
+      # session are created together or not at all: if any check fails, nothing is written and no email is sent. The
+      # response's `verification_link` describes the session, and is `null` when you don't ask for a link.
+      #
+      # **API key access:** a scoped API key needs `users` write. With `send_verification_link: true` it also needs
+      # `sessions` write, or the call answers `403` before anything is written. Full-access keys are unaffected. See
+      # [API keys](/console/api-keys).
+      #
+      # +POST /v3/users/create/+
+      #
+      # @param vendor_data [String] Your unique identifier for this user (free-form string, NOT a UUID). Must be
+      #   unique among the application's users; matched exactly as sent.
+      # @param full_name [String, nil] Full legal name of the user.
+      # @param display_name [String, nil] Friendly display name shown in the console (takes precedence over
+      #   `full_name` for UI display).
+      # @param date_of_birth [Date, String, nil] Date of birth in `YYYY-MM-DD` format.
+      # @param status [String] Initial lifecycle status. Defaults to `ACTIVE`.
+      # @param metadata [Hash, nil] Arbitrary JSON object you attach to the user. Defaults to `{}`.
+      # @param approved_emails [Array<String>] Pre-trusted email addresses for this user, e.g. `["john@example.com"]`.
+      # @param approved_phones [Array<String>] Pre-trusted phone numbers for this user, e.g. `["+14155551234"]`.
+      # @param issuing_states [Array<String>] Pre-recorded issuing countries (ISO 3166-1 alpha-3), e.g. `["USA"]`.
+      # @param first_name [String] Given name. When `full_name` is not sent, Didit joins `first_name` and `last_name`
+      #   with a space into `full_name`. Not returned as a separate field.
+      # @param last_name [String] Family name. Joined with `first_name` into `full_name` when `full_name` is not sent.
+      #   Not returned as a separate field.
+      # @param email [String] Contact email, stored in `metadata.contact.email` (it replaces an `email` you send
+      #   inside `metadata.contact`). Required when `send_verification_link` is `true`: the link is sent to this
+      #   address. If `metadata.contact` is not a JSON object, the call answers `400` on this field.
+      # @param phone_number [String] Contact phone number, stored in `metadata.contact.phone_number`. If
+      #   `metadata.contact` is not a JSON object, the call answers `400` on this field.
+      # @param country [String] Country as an ISO 3166 code, alpha-2 or alpha-3 (`ES` or `ESP`). Stored uppercased in
+      #   `metadata.address.country`. If `metadata.address` is not a JSON object, the call answers `400` on this field.
+      # @param send_verification_link [Boolean] When `true`, Didit creates a verification session for the person on
+      #   `workflow_id` and emails them the link at `email`. Requires `email` and `workflow_id`. A scoped API key also
+      #   needs `sessions` write.
+      # @param workflow_id [String] The workflow of the verification session. Required when `send_verification_link`
+      #   is `true`. It must verify a person: a Business Verification (KYB) workflow is refused. Ignored otherwise.
+      # @param language [String] Language of the verification email, as a [supported
+      #   language](/integration/supported-languages) code. English when omitted. Ignored when `send_verification_link`
+      #   is not `true`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::UsersCreateResponse]
+      def create(
+        vendor_data:,
+        full_name: OMIT,
+        display_name: OMIT,
+        date_of_birth: OMIT,
+        status: OMIT,
+        metadata: OMIT,
+        approved_emails: OMIT,
+        approved_phones: OMIT,
+        issuing_states: OMIT,
+        first_name: OMIT,
+        last_name: OMIT,
+        email: OMIT,
+        phone_number: OMIT,
+        country: OMIT,
+        send_verification_link: OMIT,
+        workflow_id: OMIT,
+        language: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/users/create/",
+          body: {
+            "vendor_data" => vendor_data,
+            "full_name" => full_name,
+            "display_name" => display_name,
+            "date_of_birth" => date_of_birth,
+            "status" => status,
+            "metadata" => metadata,
+            "approved_emails" => approved_emails,
+            "approved_phones" => approved_phones,
+            "issuing_states" => issuing_states,
+            "first_name" => first_name,
+            "last_name" => last_name,
+            "email" => email,
+            "phone_number" => phone_number,
+            "country" => country,
+            "send_verification_link" => send_verification_link,
+            "workflow_id" => workflow_id,
+            "language" => language
+          },
+          response: Types::UsersCreateResponse,
+          request_options: request_options
+        )
+      end
+
+      # Download the full user history PDF report
+      #
+      # Render and download one compliance-ready PDF containing the full verification history of the user identified
+      # by `vendor_data`. It is the same document the Console produces from **User detail → Actions → Download PDF**,
+      # so periodic compliance exports no longer need a person clicking in the Console.
+      #
+      # **What the report contains.** A cover page with the profile summary (name, date of birth, issuing states,
+      # approved emails and phones), the latest status of every feature, the session counters and an index of the
+      # sessions included - followed by the standard report of every included session, in chronological order (oldest
+      # first). Each session report is the same document `GET /v3/session/{sessionId}/generate-pdf/` returns for that
+      # session.
+      #
+      # **Eligible sessions.** Only User Verification (KYC) sessions in `Approved`, `Declined`, `In Review` or `Kyc
+      # Expired` are included; sessions in any other status are skipped. If the user has no session in one of those
+      # statuses the endpoint returns `403` - see below.
+      #
+      # **Cap.** The report is capped at the **20 most recent** reportable sessions. When a user has more, the newest
+      # 20 are included and the cover page states how many older sessions were left out. Use `GET
+      # /v3/sessions/?vendor_data=…` for the complete list as JSON.
+      #
+      # **Branding.** If your application has white-label customization, the cover and every session report are
+      # rendered with your logo and privacy-policy URL; otherwise they carry Didit branding. Reports are rendered in
+      # English - there is no language parameter.
+      #
+      # **No caching.** Every call re-renders the PDF from the current data, so a report generated after a manual
+      # review reflects the reviewer's decision. Two calls for the same user can produce byte-different files -
+      # archive the downloaded file if you need an immutable copy.
+      #
+      # **Latency.** Rendering is synchronous and downloads every stored image of every included session, so a user
+      # with many media-heavy sessions can take tens of seconds. Use a generous client read timeout (120 s
+      # recommended) and stream the body to disk. Generation stops at a server-side time budget instead of running
+      # until your client gives up: if that budget is reached, the response is still a valid PDF containing the most
+      # recent sessions, and the cover states how many were omitted.
+      #
+      # **Scope.** The user is resolved inside the application that owns the API key. A key can never export a user of
+      # another application - such a user does not exist for it and the endpoint returns `404`.
+      #
+      # **Trailing slash.** The canonical route ends with a trailing slash (`…/generate-pdf/`). A request without it
+      # is served directly with the same response - there is no `301` redirect, so no client has to follow redirects
+      # and `curl` does not need `-L`. Use the slashed URL as in the samples.
+      #
+      # +GET /v3/users/{vendor_data}/generate-pdf/+
+      #
+      # @param vendor_data [String] Your unique identifier for the user - a free-form string (NOT a UUID). This is the
+      #   same value you passed as `vendor_data` when creating the user's sessions, matched exactly as sent. URL-encode
+      #   it; a value containing `/` cannot be addressed by this route.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [String, nil] the body bytes, or nil when a block receives the chunks
+      def generate_pdf(vendor_data, request_options: nil, &block)
+        @client.request(
+          :get,
+          "/v3/users/{vendor_data}/generate-pdf/",
+          path_params: { "vendor_data" => vendor_data },
+          response: :binary,
+          accept: "application/pdf, application/json",
+          request_options: request_options, &block
+        )
+      end
+
+      # List users
+      #
+      # List [users](/entities/users) Didit assembles from KYC sessions sharing the same `vendor_data` (free-form
+      # string, NOT a UUID), plus users created via the API. Paginated, ordered by `last_session_at` desc. This
+      # endpoint does not support filtering or search parameters - fetch pages and filter client-side.
+      #
+      # +GET /v3/users/+
+      #
+      # @param limit [Integer] Page size. Defaults to 50 when omitted. There is no enforced maximum, but keep pages
+      #   small for latency.
+      # @param offset [Integer] Zero-based offset of the first record to return. Prefer following the `next` URL from
+      #   the previous page over computing this by hand.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Didit::Types::UserListItem>]
+      def list(limit: OMIT, offset: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/users/",
+          query: {
+            "limit" => limit,
+            "offset" => offset
+          },
+          page: Types::UserListItem,
+          request_options: request_options
+        )
+      end
+
+      # List networks for a user
+      #
+      # List the networks a vendor user belongs to.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/users/{vendor_user_uuid}/networks/+
+      #
+      # @param vendor_user_uuid [String] Vendor user UUID.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::EntityNetworkMembershipList]
+      def list_networks(vendor_user_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/users/{vendor_user_uuid}/networks/",
+          path_params: { "vendor_user_uuid" => vendor_user_uuid },
+          scope: :application,
+          response: Types::EntityNetworkMembershipList,
+          request_options: request_options
+        )
+      end
+
+      # Get user
+      #
+      # Fetch one [user](/entities/users) by `vendor_data` (exact match). Adds `metadata`, `comments`, and
+      # `updated_at` to the list view, and switches `tags` to the detailed tag-link shape.
+      #
+      # +GET /v3/users/{vendor_data}/+
+      #
+      # @param vendor_data [String] Your unique identifier for the user - a free-form string (NOT a UUID). This is the
+      #   same value you passed as `vendor_data` when creating the session that first introduced this user, matched
+      #   exactly as sent.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::UserDetailItem]
+      def retrieve(vendor_data, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/users/{vendor_data}/",
+          path_params: { "vendor_data" => vendor_data },
+          response: Types::UserDetailItem,
+          request_options: request_options
+        )
+      end
+
+      # Get AML ongoing monitoring job
+      #
+      # Progress and per-outcome counters of a monitoring toggle job. Poll every couple of seconds while status is
+      # PENDING or PROCESSING.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/{job_id}/+
+      #
+      # @param job_id [String] Monitoring job UUID returned by the toggle endpoint.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::OngoingMonitoringJob]
+      def retrieve_ongoing_monitoring_job(job_id, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/{job_id}/",
+          path_params: { "job_id" => job_id },
+          scope: :application,
+          response: Types::OngoingMonitoringJob,
+          request_options: request_options
+        )
+      end
+
+      # Enable or disable AML ongoing monitoring for users
+      #
+      # Turns AML ongoing monitoring on or off for the selected users, with the same semantics as the Business
+      # Console. Exactly one monitored AML screening is kept per user, so a profile that verified several times is
+      # monitored and billed once; disabling turns monitoring off across all of the profile's screenings. Users
+      # without any AML screening are screened first (billed as a regular AML screening) when they have the full name,
+      # date of birth and country needed; otherwise they are reported as `skipped_no_identity_data`.
+      #
+      # Set `estimate_only: true` to preview counts and costs without writing anything. Selections of 20 profiles or
+      # fewer resolve inline and return `200` with the completed job; larger selections return `202` and run in the
+      # background - poll [Get AML monitoring job](#get-/v3/aml-monitoring/jobs/-job_id-/) with the returned `job_id`.
+      # Enabling is refused with `403` when the organization balance does not cover the estimate. Identifiers that
+      # match nothing are listed in `unmatched` and never fail the request: a selection that matches nothing completes
+      # as an empty job (`total` 0), the same convention as the batch delete endpoints.
+      #
+      # +POST /v3/users/aml-monitoring/+
+      #
+      # @param is_enabled [Boolean] true to enable monitoring, false to disable it.
+      # @param estimate_only [Boolean] When true, returns the cost estimate and performs no writes - no screening, no
+      #   billing, no job.
+      # @param vendor_data_list [Array<String>] Your own identifiers of the users to toggle, matched exactly as sent.
+      # @param didit_internal_id_list [Array<String>] Didit internal ids of the users to toggle - the
+      #   `didit_internal_id` returned by the create, get and list endpoints.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::AMLMonitoringToggleResult, Didit::Types::AMLMonitoringJob]
+      def set_aml_monitoring(
+        is_enabled:,
+        estimate_only: OMIT,
+        vendor_data_list: OMIT,
+        didit_internal_id_list: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/users/aml-monitoring/",
+          body: {
+            "is_enabled" => is_enabled,
+            "estimate_only" => estimate_only,
+            "vendor_data_list" => vendor_data_list,
+            "didit_internal_id_list" => didit_internal_id_list
+          },
+          response: { 200 => Types::AMLMonitoringToggleResult, 202 => Types::AMLMonitoringJob },
+          request_options: request_options
+        )
+      end
+
+      # Toggle AML ongoing monitoring for users
+      #
+      # Enables or disables AML ongoing monitoring at the user level. Exactly one monitored AML screening is kept per
+      # user; users without any AML screening (for example imported users) get one created and screened first, billed
+      # as a regular AML screening. Set estimate_only to preview counts and costs without writing. Batches of 20 or
+      # fewer resolve inline (200, COMPLETED); larger batches return 202 and run asynchronously.
+      #
+      # +PATCH /v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/+
+      #
+      # @param is_enabled [Boolean] true to enable monitoring, false to disable it.
+      # @param estimate_only [Boolean] When true, returns the cost estimate and performs no writes.
+      # @param update_all [Boolean] Apply to every entity of the application (scoped by the filter_* params when
+      #   present).
+      # @param filter_search [String]
+      # @param filter_status [Array<String>]
+      # @param filter_country [String]
+      # @param filter_date_from [Date, String]
+      # @param filter_date_to [Date, String]
+      # @param didit_internal_id_list [Array<String>] Entities to toggle. Required unless update_all is true.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::OngoingMonitoringToggleResult, Didit::Types::OngoingMonitoringJob]
+      def set_ongoing_monitoring(
+        is_enabled:,
+        estimate_only: OMIT,
+        update_all: OMIT,
+        filter_search: OMIT,
+        filter_status: OMIT,
+        filter_country: OMIT,
+        filter_date_from: OMIT,
+        filter_date_to: OMIT,
+        didit_internal_id_list: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :patch,
+          "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/",
+          body: {
+            "is_enabled" => is_enabled,
+            "estimate_only" => estimate_only,
+            "update_all" => update_all,
+            "filter_search" => filter_search,
+            "filter_status" => filter_status,
+            "filter_country" => filter_country,
+            "filter_date_from" => filter_date_from,
+            "filter_date_to" => filter_date_to,
+            "didit_internal_id_list" => didit_internal_id_list
+          },
+          scope: :application,
+          response: { 200 => Types::OngoingMonitoringToggleResult, 202 => Types::OngoingMonitoringJob },
+          request_options: request_options
+        )
+      end
+
+      # Update user
+      #
+      # Partial update of a user: `display_name`, `full_name`, `date_of_birth`, `status`, `metadata`,
+      # `approved_emails`/`approved_phones`/`issuing_states`. `metadata` fully replaces. Changing `status` here works
+      # like [Update User Status](#patch-/v3/users/-vendor_data-/update-status/): it records a `STATUS_CHANGED`
+      # activity with the optional `reason`, and `BLOCKED` adds the `vendor_data` to the system blocklist (moving away
+      # from `BLOCKED` removes that entry). Changes to `display_name`, `full_name`, `date_of_birth` or `metadata` are
+      # recorded as a `PROFILE_UPDATED` activity.
+      #
+      # +PATCH /v3/users/{vendor_data}/+
+      #
+      # @param vendor_data [String] Your unique identifier for the user (free-form string, NOT a UUID).
+      # @param full_name [String, nil] Full name of the user
+      # @param display_name [String, nil] Custom display name for this user
+      # @param date_of_birth [Date, String, nil] Date of birth in YYYY-MM-DD format
+      # @param status [String] User lifecycle status. A change is recorded as a `STATUS_CHANGED` activity, and
+      #   `BLOCKED` adds the `vendor_data` to the system blocklist (moving away from `BLOCKED` removes that entry).
+      # @param metadata [Hash, nil] Arbitrary JSON object you attach to the user. **Fully replaces** the existing
+      #   metadata on update - merge client-side if you only want to add keys.
+      # @param approved_emails [Array<String>] Verified email addresses for this user, e.g. `["john@example.com"]`.
+      #   Fully replaces the stored list.
+      # @param approved_phones [Array<String>] Verified phone numbers for this user. Fully replaces the stored list.
+      # @param issuing_states [Array<String>] Issuing countries (ISO 3166-1 alpha-3), e.g. `["USA"]`. Fully replaces
+      #   the stored list.
+      # @param reason [String, nil] Why the status changed. Recorded on the status-change entry of the user's activity
+      #   (`comments[].comment`, and **Activity** in the Business Console), only when the status actually changes.
+      #   Webhooks do not carry it.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::UserDetailItem]
+      def update(
+        vendor_data,
+        full_name: OMIT,
+        display_name: OMIT,
+        date_of_birth: OMIT,
+        status: OMIT,
+        metadata: OMIT,
+        approved_emails: OMIT,
+        approved_phones: OMIT,
+        issuing_states: OMIT,
+        reason: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :patch,
+          "/v3/users/{vendor_data}/",
+          path_params: { "vendor_data" => vendor_data },
+          body: {
+            "full_name" => full_name,
+            "display_name" => display_name,
+            "date_of_birth" => date_of_birth,
+            "status" => status,
+            "metadata" => metadata,
+            "approved_emails" => approved_emails,
+            "approved_phones" => approved_phones,
+            "issuing_states" => issuing_states,
+            "reason" => reason
+          },
+          response: Types::UserDetailItem,
+          request_options: request_options
+        )
+      end
+
+      # Update user status
+      #
+      # Flip only the lifecycle `status` of a user: `ACTIVE`, `FLAGGED` or `BLOCKED` (not session statuses). `BLOCKED`
+      # adds the `vendor_data` to the system blocklist; moving away from `BLOCKED` removes that entry. Each change is
+      # recorded as a `STATUS_CHANGED` activity on the user, with the optional `reason` as its `comment`. Sending the
+      # current status changes nothing and records no `reason`. The `user.status.updated` webhook does not carry
+      # `reason`.
+      #
+      # +PATCH /v3/users/{vendor_data}/update-status/+
+      #
+      # @param vendor_data [String] Your unique identifier for the user.
+      # @param status [String] New lifecycle status. `BLOCKED` also adds the `vendor_data` to the system blocklist.
+      # @param reason [String, nil] Why the status changed. Recorded on the status-change entry of the user's activity
+      #   (`comments[].comment`, and **Activity** in the Business Console), only when the status actually changes.
+      #   Webhooks do not carry it.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::UserDetailItem]
+      def update_status(vendor_data, status:, reason: OMIT, request_options: nil)
+        @client.request(
+          :patch,
+          "/v3/users/{vendor_data}/update-status/",
+          path_params: { "vendor_data" => vendor_data },
+          body: {
+            "status" => status,
+            "reason" => reason
+          },
+          response: Types::UserDetailItem,
+          request_options: request_options
+        )
+      end
+
+      # Upload user face
+      #
+      # Attach a trusted imported face image to an existing User profile. Use this after creating or retrieving a User
+      # by `vendor_data` and reading its `didit_internal_id`. The uploaded face is stored on the User profile and
+      # indexed for duplicate detection and face search. It is not added to a face blocklist.
+      #
+      # +POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/+
+      #
+      # @param didit_internal_id [String] Didit's internal User UUID, returned as `didit_internal_id` by `GET
+      #   /v3/users/{vendor_data}/` and `POST /v3/users/create/`.
+      # @param image [String] Raw base64-encoded JPG or PNG face image. Do not include a `data:image/...;base64,`
+      #   prefix. Max decoded size: 2 MB.
+      # @param comment [String] Optional operator-visible note for the uploaded face.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::UsersUploadFaceResponse]
+      def upload_face(didit_internal_id, image:, comment: OMIT, request_options: nil)
+        @client.request(
+          :post,
+          "/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/",
+          path_params: { "didit_internal_id" => didit_internal_id },
+          body: {
+            "image" => image,
+            "comment" => comment
+          },
+          scope: :application,
+          response: Types::UsersUploadFaceResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end