didit-sdk 1.0.0

data/lib/didit/resources/account.rb

@@ -0,0 +1,309 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +account+ resource.
+    class Account < Didit::Resource
+      # @return [Didit::Resources::Account::Applications]
+      def applications
+        @applications ||= Applications.new(@client)
+      end
+
+      # @return [Didit::Resources::Account::Organizations]
+      def organizations
+        @organizations ||= Organizations.new(@client)
+      end
+
+      # Programmatic Login
+      #
+      # Authenticate any verified email/password Didit account and receive an RS256 JWT pair (default lifetime
+      # 86400s). Console-created email/password accounts can use this endpoint; OAuth-only console accounts must set a
+      # password first.
+      #
+      # +POST /programmatic/login/+
+      #
+      # @param email [String]
+      # @param password [String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::LoginResponse]
+      def login(email:, password:, request_options: nil)
+        @client.request(
+          :post,
+          "/programmatic/login/",
+          body: {
+            "email" => email,
+            "password" => password
+          },
+          auth: :none,
+          api: :account,
+          response: Types::LoginResponse,
+          request_options: request_options
+        )
+      end
+
+      # Register Account
+      #
+      # Step 1 of programmatic onboarding. Creates a pending account and emails a 6-char code (10 min TTL). The
+      # address is checked before any account is created: one that cannot receive the code returns 400
+      # `email_undeliverable`. Rate limits: 5/IP/hour, plus a shared hourly budget per network (/24 for IPv4, /64 for
+      # IPv6).
+      #
+      # +POST /programmatic/register/+
+      #
+      # @param email [String] Any valid email address (personal, work, alias). Used as the unique account identifier.
+      # @param password [String] Minimum 8 characters. Must contain at least one uppercase letter (`A-Z`), one
+      #   lowercase letter (`a-z`), one digit (`0-9`), and one special character from `!@#$%^&*()_+-=[]{}|;:,.<>?`.
+      #   Validation reports one failed rule at a time.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::RegisterResponse]
+      def register(email:, password:, request_options: nil)
+        @client.request(
+          :post,
+          "/programmatic/register/",
+          body: {
+            "email" => email,
+            "password" => password
+          },
+          auth: :none,
+          api: :account,
+          response: Types::RegisterResponse,
+          request_options: request_options
+        )
+      end
+
+      # Resend the email verification code
+      #
+      # Resend the 6-character verification code for an unverified programmatic account. Requires the account's email
+      # and password so only the owner can trigger a new code (no console Basic Auth). A fresh code replaces the
+      # previous one and is valid for 10 minutes.
+      #
+      # Rate limits: a per-email cooldown of 60 seconds between resends (HTTP 429 with `Retry-After`), and the same
+      # 5-per-IP-per-hour and per-network hourly budgets as registration.
+      #
+      # +POST /programmatic/resend-otp/+
+      #
+      # @param email [String] Email of the pending (unverified) account.
+      # @param password [String] Password chosen at registration.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::AccountResendOtpResponse]
+      def resend_otp(email:, password:, request_options: nil)
+        @client.request(
+          :post,
+          "/programmatic/resend-otp/",
+          body: {
+            "email" => email,
+            "password" => password
+          },
+          auth: :none,
+          api: :account,
+          response: Types::AccountResendOtpResponse,
+          request_options: request_options
+        )
+      end
+
+      # Verify Email and Issue Credentials
+      #
+      # Step 2 of onboarding. Exchanges the 6-char code for a verified account, a default org+app, and a JWT pair.
+      # Persist the returned `api_key`.
+      #
+      # +POST /programmatic/verify-email/+
+      #
+      # @param email [String] Email used during `POST /programmatic/register/`.
+      # @param code [String] 6-character alphanumeric code from the verification email. Codes expire 10 minutes after
+      #   the most recent code was sent.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::VerifyEmailResponse]
+      def verify_email(email:, code:, request_options: nil)
+        @client.request(
+          :post,
+          "/programmatic/verify-email/",
+          body: {
+            "email" => email,
+            "code" => code
+          },
+          auth: :none,
+          api: :account,
+          response: Types::VerifyEmailResponse,
+          request_options: request_options
+        )
+      end
+
+      # The +account.applications+ resource.
+      class Applications < Didit::Resource
+        # Create Application
+        #
+        # Create an application inside an organization. The response includes `api_key`; persist it now (recoverable
+        # via GET). Requires owner/admin JWT.
+        #
+        # +POST /organizations/me/{org_id}/applications/+
+        #
+        # @param org_id [String] UUID of the organization. Look it up with `GET /organizations/me/`.
+        # @param name [String] Application display name. Defaults to `"<organization name> App"`.
+        # @param website_url [String] Website or app URL associated with this application.
+        # @param redirect_uris [Array<String>] Allowed redirect URIs for OAuth-style and verification redirect flows.
+        # @param terms_url [String] Terms of service URL shown in the verification flow.
+        # @param privacy_url [String] Privacy policy URL shown in the verification flow.
+        # @param description [String] Internal description for the application (not shown to end users).
+        # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+        # @return [Didit::Types::Application]
+        def create(
+          org_id,
+          name: OMIT,
+          website_url: OMIT,
+          redirect_uris: OMIT,
+          terms_url: OMIT,
+          privacy_url: OMIT,
+          description: OMIT,
+          request_options: nil
+        )
+          @client.request(
+            :post,
+            "/organizations/me/{org_id}/applications/",
+            path_params: { "org_id" => org_id },
+            body: {
+              "name" => name,
+              "website_url" => website_url,
+              "redirect_uris" => redirect_uris,
+              "terms_url" => terms_url,
+              "privacy_url" => privacy_url,
+              "description" => description
+            },
+            auth: :account_token,
+            api: :account,
+            response: Types::Application,
+            request_options: request_options
+          )
+        end
+
+        # List the organization's applications
+        #
+        # List the organization's applications, 50 per page by default. Use this to discover `app_id` values when
+        # recovering credentials from a new machine, then call `GET /organizations/me/{org_id}/applications/{app_id}/`
+        # for the API key. Requires an owner or admin Bearer token.
+        #
+        # +GET /organizations/me/{org_id}/applications/+
+        #
+        # @param org_id [String] UUID of the organization. Look it up with `GET /organizations/me/`.
+        # @param limit [Integer] Number of applications per page. Defaults to 50.
+        # @param offset [Integer] Number of applications to skip before the page starts. Defaults to 0.
+        # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+        # @return [Didit::Page<Didit::Types::Application>]
+        def list(org_id, limit: OMIT, offset: OMIT, request_options: nil)
+          @client.request(
+            :get,
+            "/organizations/me/{org_id}/applications/",
+            path_params: { "org_id" => org_id },
+            query: {
+              "limit" => limit,
+              "offset" => offset
+            },
+            auth: :account_token,
+            api: :account,
+            page: Types::Application,
+            request_options: request_options
+          )
+        end
+
+        # Get Application Credentials
+        #
+        # Read one application's full record including `client_id` and `api_key`. Use this to recover a lost
+        # `api_key`.
+        #
+        # +GET /organizations/me/{org_id}/applications/{app_id}/+
+        #
+        # @param org_id [String] UUID of the organization that owns the application.
+        # @param app_id [String] UUID of the application whose credentials you want to read.
+        # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+        # @return [Didit::Types::Application]
+        def retrieve(org_id, app_id, request_options: nil)
+          @client.request(
+            :get,
+            "/organizations/me/{org_id}/applications/{app_id}/",
+            path_params: { "org_id" => org_id, "app_id" => app_id },
+            auth: :account_token,
+            api: :account,
+            response: Types::Application,
+            request_options: request_options
+          )
+        end
+
+        # Update Application
+        #
+        # Update application metadata (name, URLs, redirect URIs). `api_key` and `client_id` are never rotated.
+        # `products` is read-only: a `products` key in the body is ignored. Requires owner/admin JWT.
+        #
+        # +PATCH /organizations/me/{org_id}/applications/{app_id}/+
+        #
+        # @param org_id [String] UUID of the organization that owns the application.
+        # @param app_id [String] UUID of the application to update.
+        # @param name [String] Application display name.
+        # @param website_url [String] Website or app URL associated with this application.
+        # @param redirect_uris [Array<String>] Allowed redirect URIs for OAuth-style and verification redirect flows.
+        # @param terms_url [String] Terms of service URL shown in the verification flow.
+        # @param privacy_url [String] Privacy policy URL shown in the verification flow.
+        # @param description [String] Internal description for the application.
+        # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+        # @return [Didit::Types::Application]
+        def update(
+          org_id,
+          app_id,
+          name: OMIT,
+          website_url: OMIT,
+          redirect_uris: OMIT,
+          terms_url: OMIT,
+          privacy_url: OMIT,
+          description: OMIT,
+          request_options: nil
+        )
+          @client.request(
+            :patch,
+            "/organizations/me/{org_id}/applications/{app_id}/",
+            path_params: { "org_id" => org_id, "app_id" => app_id },
+            body: {
+              "name" => name,
+              "website_url" => website_url,
+              "redirect_uris" => redirect_uris,
+              "terms_url" => terms_url,
+              "privacy_url" => privacy_url,
+              "description" => description
+            },
+            auth: :account_token,
+            api: :account,
+            response: Types::Application,
+            request_options: request_options
+          )
+        end
+      end
+
+      # The +account.organizations+ resource.
+      class Organizations < Didit::Resource
+        # List My Organizations
+        #
+        # List organizations the authenticated user belongs to. Each entry's `uuid` is the `org_id` used on the
+        # application endpoints.
+        #
+        # +GET /organizations/me/+
+        #
+        # @param limit [Integer] Page size. Defaults to 50.
+        # @param offset [Integer] Zero-based offset of the first result.
+        # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+        # @return [Didit::Page<Didit::Types::Organization>]
+        def list(limit: OMIT, offset: OMIT, request_options: nil)
+          @client.request(
+            :get,
+            "/organizations/me/",
+            query: {
+              "limit" => limit,
+              "offset" => offset
+            },
+            auth: :account_token,
+            api: :account,
+            page: Types::Organization,
+            request_options: request_options
+          )
+        end
+      end
+    end
+  end
+end

data/lib/didit/resources/address_validation.rb

@@ -0,0 +1,73 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +address_validation+ resource.
+    class AddressValidation < Didit::Resource
+      # Validate an address
+      #
+      # Confirm that an address exists and get it back normalised: its delivery lines, components and coordinates. It
+      # confirms the address only; it never links the address to a person.
+      #
+      # **Request.** Send the address on one line (`address`) or as structured fields (`address_line_1` and,
+      # optionally, `address_line_2`, `city`, `region`, `postal_code`), never both, and always its `country` (ISO
+      # 3166-1 alpha-2 or alpha-3).
+      #
+      # **Result.** `address_validation.status` is `verified` (confirmed to the building), `partially_verified`
+      # (confirmed only to the street or above), `not_verified` (only the region or city matched, or nothing did) or
+      # `unavailable` (the validation could not run). HTTP is `200` for every completed request, `unavailable`
+      # included; retry an `unavailable` result later.
+      #
+      # **Billing.** A live call costs $0.10 per validated address. An `unavailable` result is not charged. Nothing is
+      # stored apart from the usage record: no session is created and the result is returned only in this response.
+      #
+      # **Sandbox.** Sandbox keys validate the request and always return a deterministic `verified` result that echoes
+      # the address sent, without consuming credits.
+      #
+      # **Authentication.** Send your application's API key in `x-api-key`. Missing or invalid credentials return
+      # `403` - this API never returns `401`.
+      #
+      # **Rate limit.** Shared write budget of 300 requests per minute per API key across all POST/PATCH/DELETE
+      # endpoints.
+      #
+      # +POST /v3/address-validation/+
+      #
+      # @param country [String] ISO 3166-1 alpha-2 or alpha-3 code of the address's country.
+      # @param address [String] The whole address on one line.
+      # @param address_line_1 [String] Street and number.
+      # @param address_line_2 [String] Apartment, suite, floor or building.
+      # @param city [String] City or locality.
+      # @param region [String] State, province or region.
+      # @param postal_code [String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::AddressValidationResponse]
+      def validate(
+        country:,
+        address: OMIT,
+        address_line_1: OMIT,
+        address_line_2: OMIT,
+        city: OMIT,
+        region: OMIT,
+        postal_code: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/address-validation/",
+          body: {
+            "country" => country,
+            "address" => address,
+            "address_line_1" => address_line_1,
+            "address_line_2" => address_line_2,
+            "city" => city,
+            "region" => region,
+            "postal_code" => postal_code
+          },
+          response: Types::AddressValidationResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end

data/lib/didit/resources/age_estimation.rb

@@ -0,0 +1,110 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +age_estimation+ resource.
+    class AgeEstimation < Didit::Resource
+      # Age Estimation (face age + passive liveness)
+      #
+      # Estimate a person's age from a single face photo and run a passive liveness check in the same call - returns
+      # the model-predicted `age_estimation` (in years), a liveness `score` (0-100), and an `Approved`/`Declined`
+      # `status`. The age is **model-predicted from the face, not verified against a document** - use it for age gates
+      # and low-friction checks, not as legal proof of age.
+      #
+      # **How it works.** The image is analyzed for faces (set `rotate_image=true` if captures may be sideways or
+      # upside down); each detected face gets an estimated age, and the largest face in the frame drives
+      # `age_estimation`. In parallel, a passive liveness model scores whether the photo shows a live person (no user
+      # challenge required) and detects presentation attacks (photos of photos, screens, masks). Submit one clear,
+      # front-facing, well-lit face per image for best results.
+      #
+      # **Decision logic.** Any warning declines: `status` is `Approved` only when the `warnings` array is empty. A
+      # liveness `score` at or below `face_liveness_score_decline_threshold` (default `30`) adds `LOW_LIVENESS_SCORE`;
+      # a detected attack adds `LIVENESS_FACE_ATTACK`; no face found by the liveness model adds `NO_FACE_DETECTED`; no
+      # estimable face age adds `AGE_NOT_DETECTED` (`age_estimation` is `null`); an estimated age below
+      # `age_estimation_decline_threshold` (default `18`) adds `AGE_BELOW_MINIMUM`. Borderline ages near your
+      # threshold deserve a fallback to document-based verification - the model's error grows for faces close to the
+      # limit.
+      #
+      # **Billing.** Each `200` response consumes one Age Estimation API credit (paid from your plan credit or top-up
+      # balance). When the organization's balance cannot cover the call, the endpoint returns `403` with the
+      # not-enough-credits error before any image processing.
+      #
+      # **Session persistence (`save_api_request`, default `true`).** When `true`, the call is persisted as an
+      # API-type session: it appears in the Business Console, the returned `request_id` is a real session id you can
+      # pass to `GET /v3/session/{sessionId}/decision/` (the result is exposed there in `liveness_checks[]`, with
+      # `features: ["AGE_ESTIMATION"]`), the face crop and reference image are stored, the face embedding is added to
+      # your application's face index (used by face search and duplicate detection), and a `status.updated` webhook is
+      # emitted. When `false`, nothing is stored and `request_id` is a one-off correlation UUID that cannot be looked
+      # up later.
+      #
+      # **Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still
+      # returns `400`), the endpoint returns a static `Approved` mock payload (`age_estimation: 30`, no warnings), no
+      # session is persisted, and no credits are consumed.
+      #
+      # **Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials
+      # return `403` (`{"detail": "You do not have permission to perform this action."}`) - this API never returns
+      # `401`.
+      #
+      # **Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints;
+      # exceeding it returns `429`.
+      #
+      # +POST /v3/age-estimation/+
+      #
+      # @param user_image [Pathname, IO, String, Didit::FilePart] Face photo to analyze (e.g. a selfie). Submit a
+      #   single front-facing photo with the subject's face clearly visible and well lit. Allowed extensions: `tiff`,
+      #   `jpg`, `jpeg`, `png`, `webp` (no PDF). Maximum upload size: **5 MB** (larger files are rejected with `400`).
+      #   Images are automatically compressed to ~0.3 MB before processing, so very high resolutions do not improve
+      #   accuracy.
+      # @param face_liveness_score_decline_threshold [Numeric] Liveness threshold (0-100). A liveness `score` **at or
+      #   below** this value adds a `LOW_LIVENESS_SCORE` warning and declines. Raise it for stricter anti-spoofing;
+      #   values outside 0-100 return `400`.
+      # @param age_estimation_decline_threshold [Integer] Minimum acceptable estimated age in years. An estimated age
+      #   **below** this value adds an `AGE_BELOW_MINIMUM` warning and declines. Set `0` to disable the age check (the
+      #   call then only runs liveness + age estimation without an age-based decision).
+      # @param rotate_image [Boolean] When `true`, the service tries the input image in 90-degree increments (0, 90,
+      #   180, 270) and uses the orientation that yields the best face detection - useful for mobile captures with
+      #   missing EXIF orientation. Adds latency, so only enable it if you cannot guarantee upright images.
+      # @param save_api_request [Boolean] When `true` (default), persists the call as an API-type session - visible in
+      #   the Business Console, retrievable via `GET /v3/session/{sessionId}/decision/` using the returned `request_id`,
+      #   announced through a `status.updated` webhook, and with the detected face added to your application's face
+      #   index. When `false`, nothing is stored and `request_id` is a transient UUID for response correlation only...
+      # @param vendor_data [String] Optional opaque string (your internal user id, email, UUID…) stored on the
+      #   persisted session and echoed back in the response. Use it to correlate API calls with your own records and to
+      #   filter sessions later.
+      # @param metadata [Hash] Optional JSON object stored with the session (when `save_api_request=true`) and echoed
+      #   back in the response. In multipart requests, send it as a JSON-encoded string field (e.g.
+      #   `metadata={"flow":"age-gate"}`) - it is parsed into an object.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::AgeEstimationEstimateResponse]
+      def estimate(
+        user_image:,
+        face_liveness_score_decline_threshold: OMIT,
+        age_estimation_decline_threshold: OMIT,
+        rotate_image: OMIT,
+        save_api_request: OMIT,
+        vendor_data: OMIT,
+        metadata: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/age-estimation/",
+          body: {
+            "user_image" => user_image,
+            "face_liveness_score_decline_threshold" => face_liveness_score_decline_threshold,
+            "age_estimation_decline_threshold" => age_estimation_decline_threshold,
+            "rotate_image" => rotate_image,
+            "save_api_request" => save_api_request,
+            "vendor_data" => vendor_data,
+            "metadata" => metadata
+          },
+          encoding: :multipart,
+          file_fields: %w[user_image],
+          response: Types::AgeEstimationEstimateResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end

data/lib/didit/resources/aml.rb

@@ -0,0 +1,166 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +aml+ resource.
+    class Aml < Didit::Resource
+      # Get AML dataset freshness
+      #
+      # Report how current the datasets behind AML screening are, per source family (`sanctions`, `pep`, `warnings`,
+      # `adverse_media`), as audit evidence for [ongoing AML
+      # monitoring](https://docs.didit.me/core-technology/aml-screening/continuous-monitoring-aml-screening#proving-that-monitoring-ran).
+      # The answer is platform-wide: no session in the path, no customer data in the body, the same answer for every
+      # application.
+      #
+      # Always `200` for an accepted key. Check `availability` first: when it is not `available`, `dataset_freshness`
+      # is `null`. Dates are never estimated: a family whose datasets reported no date is absent from `sources`, and a
+      # family where only some datasets reported one has `oldest_updated_at: null`. Readings are taken while ongoing
+      # monitoring runs, not on each call; `captured_at` says when.
+      #
+      # A scoped API key needs `sessions: read`; a key limited to some workflows or to approved sessions cannot call
+      # this endpoint. Nothing is billed.
+      #
+      # +GET /v3/aml/dataset-freshness/+
+      #
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::AmlRetrieveDatasetFreshnessResponse]
+      def retrieve_dataset_freshness(request_options: nil)
+        @client.request(
+          :get,
+          "/v3/aml/dataset-freshness/",
+          response: Types::AmlRetrieveDatasetFreshnessResponse,
+          request_options: request_options
+        )
+      end
+
+      # AML screening (standalone)
+      #
+      # Screen a person or company against PEP, sanctions, warning/watchlist, and adverse-media datasets in one call.
+      #
+      # **Two-score model.** Each hit carries a `match_score` (0-100, identity confidence) and a `risk_score` (0-100,
+      # entity risk). Hits whose `match_score` is below `aml_match_score_threshold` (default **93**) are tagged
+      # `review_status: "False Positive"` and ignored for risk purposes; the highest `risk_score` among the remaining
+      # hits becomes `aml.score`. The final `aml.status` follows your thresholds: `score` >
+      # `aml_score_review_threshold` (default **100**) → `Declined`; `score` > `aml_score_approve_threshold` (default
+      # **80**) → `In Review`; otherwise `Approved`. Whenever `score` is non-zero and ≥ the approve threshold a
+      # `POSSIBLE_MATCH_FOUND` warning is added (a score of exactly 0 never warns).
+      #
+      # **Match-score weights.** `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` must sum to exactly 100
+      # (defaults 60/25/15). Components missing from the request are re-normalized away; a matching `document_number`
+      # acts as a golden key that overrides `match_score` to 100.
+      #
+      # **Latency.** Plain screenings typically complete in a few seconds. With `include_adverse_media=true` the API
+      # waits for adverse-media enrichment (an initial ~5 s pause plus up to ~25 s of polling) - configure a client
+      # timeout of **at least 60 seconds**.
+      #
+      # **Persistence.** `save_api_request` defaults to **true**: the screening is stored as a session (`request_id`
+      # works with `GET /v3/session/{sessionId}/decision/`), it appears in the console, a `status.updated` webhook
+      # fires, and hit review statuses can be updated later. With `save_api_request=false` nothing is stored and
+      # `request_id` is a transient correlation id. `include_ongoing_monitoring=true` keeps re-screening the profile
+      # and requires `save_api_request=true` (enforced with a `400`).
+      #
+      # **Idempotency.** Send an `Idempotency-Key` header when retrying after a timeout or transient error. The key is
+      # scoped to your application and the exact request body. The first completed request stores its response; later
+      # identical retries return that same response and do not run or bill another AML screening. If the original
+      # request is still running, retry later with the same key. If the same key is reused with a different body, the
+      # API returns `409`.
+      #
+      # **Billing.** One AML API credit is charged after the first successful screening. Replayed idempotent responses
+      # are not charged again; an insufficient balance returns `403` before any new screening happens.
+      #
+      # **Sandbox.** Keys from sandbox applications skip screening and billing entirely and return a mocked result -
+      # `Approved` with zero hits unless you pass `sandbox_scenario`. `save_api_request` works the same as on live
+      # keys, so a saved sandbox screening is retrievable through `GET /v3/session/{sessionId}/decision/` and `GET
+      # /v3/session/{sessionId}/generate-pdf/`.
+      #
+      # +POST /v3/aml/+
+      #
+      # @param full_name [String] Full name of the person or company to screen. Minimum **2 characters** - the
+      #   screening provider's own floor. A shorter or blank name returns `400` on this field before any screening runs,
+      #   so nothing is billed.
+      # @param entity_type [String] Type of entity to screen. Defaults to `person`.
+      # @param date_of_birth [Date, String] Date of birth (persons) or incorporation date (companies), `YYYY-MM-DD`.
+      #   Improves match precision via the DOB weight.
+      # @param nationality [String] ISO 3166-1 **alpha-2** country code (e.g. `ES`). Invalid codes return `400`.
+      #   Improves match precision via the country weight.
+      # @param document_number [String] Identity document number. Not weighted - acts as a golden key: an exact match
+      #   overrides the hit's `match_score` to 100, a hard mismatch penalizes it. Sent to the screening provider as a
+      #   search filter only when it is **2-50 characters**; a value outside that range is accepted and stored, and the
+      #   screening still runs and is billed, just not narrowed by document number.
+      # @param aml_score_approve_threshold [Numeric] Risk-score threshold at or below which the result is `Approved`.
+      #   Must be ≤ `aml_score_review_threshold` (else `400`).
+      # @param aml_score_review_threshold [Numeric] Risk-score threshold above which the result is `Declined`. Scores
+      #   between the two thresholds produce `In Review`.
+      # @param aml_name_weight [Integer] Weight of name similarity in the per-hit match score. The three weights must
+      #   sum to exactly 100 (else `400`).
+      # @param aml_dob_weight [Integer] Weight of date of birth in the per-hit match score.
+      # @param aml_country_weight [Integer] Weight of country/nationality in the per-hit match score.
+      # @param aml_match_score_threshold [Integer] Per-hit cutoff: hits with `match_score` below this are `False
+      #   Positive` (excluded from risk assessment); at or above are `Unreviewed` possible matches.
+      # @param include_adverse_media [Boolean] Also search news media for negative coverage. Adds up to ~30 s of
+      #   latency while results are gathered - use a ≥60 s client timeout.
+      # @param include_ongoing_monitoring [Boolean] Keep re-screening this profile and push changes via webhook.
+      #   Requires `save_api_request=true` (else `400`).
+      # @param save_api_request [Boolean] Persist the screening as a session (console visibility, decision endpoint,
+      #   webhooks, hit review). Set to `false` for a stateless check.
+      # @param vendor_data [String] Your identifier for the screened user; echoed back and stored with the session.
+      # @param metadata [Hash, nil] Free-form JSON stored with the request and echoed back.
+      # @param sandbox_scenario [String] Sandbox-only scenario slug. Only accepted when the API key belongs to a
+      #   sandbox-mode application; rejected on live applications. A standalone screening has no session to arm, so the
+      #   slug goes on the screening request itself: `decline_aml_hit` returns one production-shaped hit and settles the
+      #   screening as `Declined`, `review_aml_possible_match` settles it `In Review`, and a scenario that arms no A...
+      # @param idempotency_key [String] sent as the Idempotency-Key header
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::AmlScreenResponse]
+      def screen(
+        full_name:,
+        entity_type: OMIT,
+        date_of_birth: OMIT,
+        nationality: OMIT,
+        document_number: OMIT,
+        aml_score_approve_threshold: OMIT,
+        aml_score_review_threshold: OMIT,
+        aml_name_weight: OMIT,
+        aml_dob_weight: OMIT,
+        aml_country_weight: OMIT,
+        aml_match_score_threshold: OMIT,
+        include_adverse_media: OMIT,
+        include_ongoing_monitoring: OMIT,
+        save_api_request: OMIT,
+        vendor_data: OMIT,
+        metadata: OMIT,
+        sandbox_scenario: OMIT,
+        idempotency_key: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/aml/",
+          body: {
+            "full_name" => full_name,
+            "entity_type" => entity_type,
+            "date_of_birth" => date_of_birth,
+            "nationality" => nationality,
+            "document_number" => document_number,
+            "aml_score_approve_threshold" => aml_score_approve_threshold,
+            "aml_score_review_threshold" => aml_score_review_threshold,
+            "aml_name_weight" => aml_name_weight,
+            "aml_dob_weight" => aml_dob_weight,
+            "aml_country_weight" => aml_country_weight,
+            "aml_match_score_threshold" => aml_match_score_threshold,
+            "include_adverse_media" => include_adverse_media,
+            "include_ongoing_monitoring" => include_ongoing_monitoring,
+            "save_api_request" => save_api_request,
+            "vendor_data" => vendor_data,
+            "metadata" => metadata,
+            "sandbox_scenario" => sandbox_scenario
+          },
+          headers: { "Idempotency-Key" => idempotency_key },
+          response: Types::AmlScreenResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end