didit-sdk 1.0.0

data/lib/didit/resources/phone.rb

@@ -0,0 +1,271 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +phone+ resource.
+    class Phone < Didit::Resource
+      # Risk-score a phone number
+      #
+      # Resolve a phone number and return carrier, line-type, porting, disposable-number, cross-session match, and
+      # normalized risk-intelligence signals without sending an OTP. The endpoint creates an API session and returns
+      # its id as `request_id`.
+      #
+      # **Decision.** The top-level `status` mirrors `phone.status`. It is normally `Approved`; the risk evaluation
+      # can produce `In Review` or `Declined`.
+      #
+      # **Compatibility aliases.** Live responses expose the normalized intelligence object as both
+      # `phone.phone_intelligence` and `phone.enrichment`. The values are identical. New integrations can read
+      # `phone.enrichment`. Both keys are absent when no usable intelligence data was returned.
+      #
+      # **Billing.** Live calls use Phone Risk API pricing. The request is billable once the lookup starts, even when
+      # some best-effort fields are unavailable.
+      #
+      # **Sandbox.** Sandbox keys validate the request and return deterministic approved data without sending an OTP,
+      # consuming credits, creating a session, or contributing to Networks.
+      #
+      # **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.
+      #
+      # **Social footprint.** Set `enable_social` to `true` to add a `phone_social` block: the online platforms this
+      # number is registered on, with per-category counts and any profile details available. `profiles_registered: 0`
+      # means the platforms were checked and the number was found on none of them - a valid, billable answer. The
+      # block is absent when the add-on was not requested or the check could not be completed, and it is not billed in
+      # that case. Billing adds one `phone_social` unit per request on top of this endpoint's own price.
+      #
+      # +POST /v3/phone/risk/+
+      #
+      # @param phone_number [String] Phone number to score. It is validated and normalized to E.164.
+      # @param country_code [String] Optional ISO 3166-1 alpha-2 or alpha-3 country hint for intelligence coverage.
+      # @param signals [Hash] Optional device and network context observed by your application. All fields are
+      #   optional. Passing them feeds cross-session match detection in Networks.
+      # @param vendor_data [String] Your stable reference for this request. Stored on the API session and echoed in
+      #   the response.
+      # @param metadata [Hash, nil] Your non-sensitive JSON metadata. Stored on the API session and echoed in the
+      #   response.
+      # @param enable_social [Boolean] When true, also look up the social footprint of the number - the messaging,
+      #   social, e-commerce and professional platforms it is registered on. Billed as one `phone_social` unit per
+      #   request in addition to this endpoint's own price.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::PhoneRiskResponse]
+      def assess_risk(
+        phone_number:,
+        country_code: OMIT,
+        signals: OMIT,
+        vendor_data: OMIT,
+        metadata: OMIT,
+        enable_social: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/phone/risk/",
+          body: {
+            "phone_number" => phone_number,
+            "country_code" => country_code,
+            "signals" => signals,
+            "vendor_data" => vendor_data,
+            "metadata" => metadata,
+            "enable_social" => enable_social
+          },
+          response: Types::PhoneRiskResponse,
+          request_options: request_options
+        )
+      end
+
+      # Check Phone Code
+      #
+      # Verify the OTP delivered by [`POST /v3/phone/send/`](/standalone-apis/phone-send) and get the final
+      # verification result plus phone intelligence: carrier name and line type, virtual (VoIP) and disposable flags,
+      # and duplicate usage of the number across your sessions.
+      #
+      # **How the check finds the verification.** Matching is by your application plus the E.164 `phone_number` -
+      # `request_id` is not an input. The most recent pending verification created within the last **5 minutes** is
+      # checked. If there is none (never sent, already finalized, or older than 5 minutes) the endpoint returns `200`
+      # with `status: "Expired or Not Found"`.
+      #
+      # **Attempt budget.** Each verification allows **3 code attempts**. The first two wrong codes return `status:
+      # "Failed"` with the attempts remaining and `phone: null`; the third wrong code finalizes the verification as
+      # `Declined` with a `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` warning and returns the full phone report.
+      #
+      # **Outcomes.** `Approved` - correct code and no declining risk. `Declined` - terminal: the code was correct but
+      # a declining risk matched (a `DECLINE` action below, a blocklisted or high-risk number), or the attempt budget
+      # was exhausted. `Failed` - wrong code, attempts remaining. `Expired or Not Found` - nothing to check. On
+      # `Approved`/`Declined` the `request_id` equals the send's `request_id` (the session id) and `phone` carries the
+      # full report (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); on `Failed` and
+      # `Expired or Not Found` the `request_id` is a one-off random UUID.
+      #
+      # **Risk actions.** `duplicated_phone_number_action`, `disposable_number_action`, and `voip_number_action`
+      # decide what happens when the corresponding risk is detected on a correct code: `DECLINE` flips the final
+      # status to `Declined`; `NO_ACTION` (default) records the risk in `phone.warnings` without affecting the status.
+      #
+      # **Billing.** Checks are free - delivery is billed on the send side (see [Phone Verification
+      # Pricing](/getting-started/phone-verification-pricing)).
+      #
+      # **Session persistence.** A finalized check updates the session created by the send (visible in the Business
+      # Console, queryable via `GET /v3/session/{sessionId}/decision/`) and fires a `status.updated` webhook.
+      #
+      # **Sandbox.** Sandbox API keys skip all processing: any well-formed code (4-8 digits, `123456` included)
+      # returns a static `Approved` payload with a simplified flat `phone` object (`status`, `phone_number`,
+      # `country_code`, `carrier_name`, `line_type`, `flags`); malformed input still returns `400`. Nothing is
+      # persisted.
+      #
+      # **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 limits.** Shared write budget of 300 requests/min per API key, plus the upstream anti-abuse cap of 4
+      # attempts per number per hour; exceeding either returns `429`.
+      #
+      # **Social footprint.** Set `enable_social` to `true` to add a `phone_social` block: the online platforms this
+      # number is registered on, with per-category counts and any profile details available. `profiles_registered: 0`
+      # means the platforms were checked and the number was found on none of them - a valid, billable answer. The
+      # block is absent when the add-on was not requested or the check could not be completed, and it is not billed in
+      # that case. Billing adds one `phone_social` unit per request on top of this endpoint's own price.
+      #
+      # +POST /v3/phone/check/+
+      #
+      # @param phone_number [String] The same phone number used in the matching [`POST
+      #   /v3/phone/send/`](/standalone-apis/phone-send) call, in E.164 format. This is what links the check to the
+      #   send.
+      # @param code [String] The OTP the end user received. Must be 4-8 numeric digits - anything else returns `400`
+      #   without consuming an attempt. A well-formed but wrong code returns `200` with `status: "Failed"` and consumes
+      #   one of the 3 attempts.
+      # @param duplicated_phone_number_action [String] What to do when the same number was already used by a different
+      #   user (different `vendor_data`) of your application. `DECLINE` flips the final `status` to `Declined`;
+      #   `NO_ACTION` records the risk in `phone.warnings` and fills `phone.matches`.
+      # @param disposable_number_action [String] What to do when the carrier lookup flags the number as a
+      #   temporary/burner line (`phone.is_disposable`). `DECLINE` flips the final `status` to `Declined`; `NO_ACTION`
+      #   records the risk in `phone.warnings`.
+      # @param voip_number_action [String] What to do when the carrier lookup reports a virtual line type - `voip`,
+      #   `isp`, or `vpn` (`phone.is_virtual`). `DECLINE` flips the final `status` to `Declined`; `NO_ACTION` records
+      #   the risk in `phone.warnings`.
+      # @param enable_social [Boolean] When true, also look up the social footprint of the number - the messaging,
+      #   social, e-commerce and professional platforms it is registered on. Billed as one `phone_social` unit per
+      #   request in addition to this endpoint's own price.
+      # @param phone_no_social_presence_action [String] Action when the social footprint check finds the number
+      #   registered on none of the platforms it covers. Only NO_ACTION and DECLINE are accepted on this endpoint;
+      #   REVIEW is available on the workflow configuration key of the same name.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::PhoneVerificationCheckResponse]
+      def check_code(
+        phone_number:,
+        code:,
+        duplicated_phone_number_action: OMIT,
+        disposable_number_action: OMIT,
+        voip_number_action: OMIT,
+        enable_social: OMIT,
+        phone_no_social_presence_action: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/phone/check/",
+          body: {
+            "phone_number" => phone_number,
+            "code" => code,
+            "duplicated_phone_number_action" => duplicated_phone_number_action,
+            "disposable_number_action" => disposable_number_action,
+            "voip_number_action" => voip_number_action,
+            "enable_social" => enable_social,
+            "phone_no_social_presence_action" => phone_no_social_presence_action
+          },
+          response: Types::PhoneVerificationCheckResponse,
+          request_options: request_options
+        )
+      end
+
+      # Send Phone Code
+      #
+      # Send a one-time passcode (OTP) to a phone number over WhatsApp, SMS, or another supported channel, then verify
+      # it with [`POST /v3/phone/check/`](/standalone-apis/phone-check).
+      #
+      # **How send and check pair up.** Verification state is keyed by your application plus the E.164 `phone_number`
+      # - the check call does not take `request_id`. Each new send creates a pending verification that lives for **5
+      # minutes**: call the check with the same number and the code the user received before the window closes.
+      # Calling send again for the same number while a verification is pending re-sends a code for that same
+      # verification (`status: "Retry"`, same `request_id`). At most one retry is attached this way (two sends total);
+      # a further send starts a fresh verification with a new `request_id`. The 5-minute window is measured from the
+      # first send and is not extended by retries.
+      #
+      # **Delivery channels.** `options.preferred_channel` selects the channel (`whatsapp` by default; `sms`,
+      # `telegram`, `voice`, `rcs`, `viber`, and `zalo` are also supported). When the preferred channel is unavailable
+      # for the destination country or number, delivery automatically falls back to SMS - the send still reports
+      # `Success`, and the channel actually used is reported by the check response (`phone.verification_method` and
+      # the `lifecycle` events).
+      #
+      # **Branding.** SMS codes carry your application's SMS sender name, set in the Business Console, at no extra
+      # cost. Pass `options.sms_sender_name` to sign one code with another name, or
+      # `options.use_white_label_customization: true` to fall back to your white-label public name when no sender name
+      # is set. WhatsApp codes use a fixed message; connect your own WhatsApp Business number in the Business Console
+      # to send them from your business name and number, billed at the Didit fee only.
+      #
+      # **Send statuses.** `Success` - OTP sent for a new verification; `Retry` - OTP re-sent for the pending
+      # verification; `Blocked` - the anti-fraud layer refused to send (see `reason`, e.g. `repeated_attempts`,
+      # `suspicious`, `spam`). A `Blocked` send immediately finalizes the verification as `Declined` with a high-risk
+      # warning, so a follow-up check returns `Expired or Not Found`.
+      #
+      # **Billing.** The price depends on the destination country and the channel that actually delivers the message -
+      # see [Phone Verification Pricing](/getting-started/phone-verification-pricing). Only `Blocked` sends are
+      # guaranteed free: any other unbilled send attempt is charged at verification finalization or expiration, even
+      # if delivery was never confirmed or the delivery provider reported the message undeliverable. Checks are always
+      # free. As an anti-abuse measure, phone verification is disabled until your organization's first top-up (`403`).
+      #
+      # **Session persistence.** Every new verification is persisted as an API-type session: `request_id` is a real
+      # session id you can pass to `GET /v3/session/{sessionId}/decision/`, the verification appears in the Business
+      # Console, and `status.updated` webhooks fire as it progresses.
+      #
+      # **Sandbox.** Sandbox API keys skip delivery and billing: after request validation (malformed input still
+      # returns `400`), the endpoint returns a static `Success` payload with a random `request_id`; no message is sent
+      # and nothing is persisted. Use code `123456` on the sandbox check.
+      #
+      # **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 limits.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints,
+      # plus an anti-abuse cap of 4 send attempts per phone number per hour; exceeding either returns `429`.
+      #
+      # +POST /v3/phone/send/+
+      #
+      # @param phone_number [String] Recipient phone number in E.164 format - leading `+` and country code (e.g.,
+      #   `+14155552671`). Numbers are validated and normalized to E.164; unparseable or invalid numbers return `400`
+      #   with a `phone_number` field error.
+      # @param options [Hash] OTP delivery options. All fields are optional.
+      # @param signals [Hash] Optional device and network signals about the end user, forwarded to the anti-fraud
+      #   layer to improve detection of abusive or automated traffic. All fields are optional.
+      # @param vendor_data [String] Optional caller-controlled identifier (your internal user id, an email, a UUID,
+      #   etc.) persisted on the session and echoed back in the send response, the matching check response, webhooks,
+      #   and the Business Console. Use it to correlate Didit's `request_id` with your user record.
+      # @param metadata [Hash, nil] Optional free-form JSON object persisted on the session and echoed back in the
+      #   send response, the matching check response, webhooks, and the Business Console.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::PhoneVerificationSendResponse]
+      def send_code(
+        phone_number:,
+        options: OMIT,
+        signals: OMIT,
+        vendor_data: OMIT,
+        metadata: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/phone/send/",
+          body: {
+            "phone_number" => phone_number,
+            "options" => options,
+            "signals" => signals,
+            "vendor_data" => vendor_data,
+            "metadata" => metadata
+          },
+          response: Types::PhoneVerificationSendResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end

data/lib/didit/resources/pricing.rb

@@ -0,0 +1,40 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +pricing+ resource.
+    class Pricing < Didit::Resource
+      # Get bank verification prices (public, unauthenticated)
+      #
+      # Returns the list price of each Bank Verification method in every country: bank sign-in with its balance and
+      # transactions add-ons, and the account check. Use it to quote a bank step before you build a workflow, or to
+      # show bank prices in your own product.
+      #
+      # Public: send no auth header. The response contains no organization data and is the same for every caller. It
+      # is cached publicly for one hour and carries an `ETag`, so send `If-None-Match` to get a `304 Not Modified`
+      # when nothing changed.
+      #
+      # A method is `available` only where Didit serves it in production today, and its `price_usd` is `null`
+      # everywhere else, so the feed never shows a price you cannot buy. `available: false` covers a country with no
+      # approved price, a method the country does not support, and a route that is not switched on yet.
+      #
+      # These are list prices before your plan discount. Your plan discount applies to the whole bank price, and a
+      # negotiated or contract price replaces the list price for your organization.
+      #
+      # +GET /v3/organization/bank-verification-pricing/+
+      #
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::BankVerificationPricing]
+      def bank_verification(request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/bank-verification-pricing/",
+          auth: :none,
+          response: Types::BankVerificationPricing,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end

data/lib/didit/resources/proof_of_address.rb

@@ -0,0 +1,167 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +proof_of_address+ resource.
+    class ProofOfAddress < Didit::Resource
+      # Proof of Address (document OCR + address checks)
+      #
+      # Extract and validate a Proof of Address document - utility bills, bank statements, and government-issued
+      # documents - in one call. Returns the issuer, issue/expiry dates, the holder name, the raw and parsed/geocoded
+      # address, an `Approved`/`Declined` `status`, and a `warnings` list explaining every issue found.
+      #
+      # **Latency.** Extraction is LLM-based: typical calls take **5-15 seconds**, multi-page PDFs up to **~30
+      # seconds**. Configure a client timeout of **at least 45 seconds** and do not retry before the call completes.
+      #
+      # **How it works.** The document (image or PDF, up to 15 MB; encrypted PDFs require `document_password`) is
+      # classified into a document type and subtype (e.g. `UTILITY_BILL` / `WATER_BILL`), and the issuer, dates,
+      # holder name, and address are extracted with LLM-based extraction. The address is parsed and geocoded into
+      # `poa_parsed_address`. PDF/EXIF forensics screen for tampering - modification after digital signing, known PDF
+      # editors, overlay-text manipulation, suspicious re-exports - surfacing `SUSPECTED_DOCUMENT_MANIPULATION` or
+      # `DOCUMENT_METADATA_MISMATCH`. Document age is validated against `poa_document_age_months`, and the language
+      # against `poa_languages_allowed`. If you pass `expected_address`, `expected_country`, or
+      # `expected_first_name`/`expected_last_name`, the extracted values are cross-checked and mismatches are flagged.
+      #
+      # **Decision logic.** `status` is `Approved` unless at least one warning resolves to a decline. Hard failures
+      # always decline: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`,
+      # `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, plus `UNABLE_TO_EXTRACT_ISSUE_DATE` and `POA_NAME_NOT_DETECTED` (not
+      # configurable on this endpoint). Five risk groups are configurable per request via the `poa_*_action` options
+      # (`DECLINE` or `NO_ACTION`, all defaulting to `DECLINE`). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` and
+      # `UNPARSABLE_OR_INVALID_ADDRESS` are informational on this endpoint and never decline. A document that cannot
+      # be processed at all returns `400`; a readable but problematic document returns `200` with `status: "Declined"`
+      # - always inspect `poa.status` and `poa.warnings`, not just the HTTP code.
+      #
+      # **Billing.** Each `200` response consumes one Proof of Address 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 document 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 uploaded document is stored, the returned
+      # `request_id` is a real session id you can pass to `GET /v3/session/{sessionId}/decision/` (the decision
+      # additionally exposes `document_file` and the `document_metadata` forensics, which this response omits), 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 (a fictional "Sandbox Power Co."
+      # electricity bill), 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`.
+      #
+      # Note: `FUTURE_ISSUE_DATE` and `POOR_DOCUMENT_QUALITY` exist in workflow sessions but are never produced by
+      # this standalone endpoint - a future-dated document is not auto-declined here.
+      #
+      # +POST /v3/poa/+
+      #
+      # @param document [Pathname, IO, String, Didit::FilePart] The Proof of Address document. Allowed extensions:
+      #   `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Maximum upload size: **15 MB** (larger files are rejected with
+      #   `400`). Multi-page PDFs are supported (expect higher latency); encrypted PDFs require `document_password`.
+      #   Images are automatically compressed before processing.
+      # @param document_password [String] Password to decrypt `document` when it is an encrypted PDF. Sending an
+      #   encrypted PDF without (or with a wrong) password returns `400`.
+      # @param expected_address [String] Address to verify against the document. It is geocoded and compared with the
+      #   extracted address; a mismatch (or an expected address that cannot be geocoded/verified) adds
+      #   `ADDRESS_MISMATCH_WITH_PROVIDED`, governed by `poa_address_mismatch_action`. The geocoded form is echoed back
+      #   in `expected_details_formatted_address` / `expected_details_parsed_address`.
+      # @param expected_country [String] Country to verify against the document (ISO 3166-1 code, e.g. `ARG` or `AR`).
+      #   A mismatch with the document's country adds `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, governed by
+      #   `poa_address_mismatch_action`.
+      # @param expected_first_name [String] First name to verify against `name_on_document` (fuzzy match,
+      #   transliteration-aware). A score below the match threshold adds `NAME_MISMATCH_WITH_PROVIDED`, governed by
+      #   `poa_address_mismatch_action`.
+      # @param expected_last_name [String] Last name to verify against `name_on_document`, combined with
+      #   `expected_first_name` for the match score.
+      # @param poa_languages_allowed [String] Comma-separated list of accepted document languages as ISO 639-1 codes
+      #   (e.g. `en,es,fr`). When omitted or blank, **all 51 supported languages** are accepted. A document in a
+      #   language outside the list adds `UNSUPPORTED_DOCUMENT_LANGUAGE` (governed by
+      #   `poa_unsupported_language_action`); an unknown code in the list returns `400` with the full set of supported
+      #   codes.
+      # @param poa_document_age_months [String] Comma-separated `key:value` pairs setting the maximum document age in
+      #   months per document type - keys: `utility_bill`, `bank_statement`, `government_issued_document`,
+      #   `other_poa_document`; values: `1`-`120`, or `-1` for unlimited (no age check). Defaults when omitted:
+      #   `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. A document older than
+      #   its limit declines wi...
+      # @param poa_name_mismatch_action [String] Accepted but **currently not applied** - name-mismatch warnings
+      #   (`NAME_MISMATCH_WITH_PROVIDED`) follow `poa_address_mismatch_action` instead. Set
+      #   `poa_address_mismatch_action` to control both name and address mismatch behavior.
+      # @param poa_document_issues_action [String] What to do on file-integrity problems - in practice only
+      #   `DOCUMENT_METADATA_MISMATCH` is produced by this endpoint.
+      # @param poa_document_authenticity_action [String] What to do when document manipulation is suspected
+      #   (`SUSPECTED_DOCUMENT_MANIPULATION`) - e.g. the PDF was modified after digital signing, processed by a known
+      #   PDF editor, shows overlay-text manipulation, or has inconsistent EXIF dates.
+      # @param poa_unsupported_language_action [String] What to do when the document language is outside
+      #   `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`).
+      # @param poa_address_mismatch_action [String] What to do when the extracted details disagree with the
+      #   `expected_*` fields: `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED`, and
+      #   `POA_COUNTRY_MISMATCH_WITH_PROVIDED` all follow this action.
+      # @param poa_issuer_not_identified_action [String] What to do when no issuing company/organization can be
+      #   identified on the document (`ISSUER_NOT_IDENTIFIED`).
+      # @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 uploaded document stored. 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":"onboarding"}`) - it is parsed into an object.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::ProofOfAddressVerifyResponse]
+      def verify(
+        document:,
+        document_password: OMIT,
+        expected_address: OMIT,
+        expected_country: OMIT,
+        expected_first_name: OMIT,
+        expected_last_name: OMIT,
+        poa_languages_allowed: OMIT,
+        poa_document_age_months: OMIT,
+        poa_name_mismatch_action: OMIT,
+        poa_document_issues_action: OMIT,
+        poa_document_authenticity_action: OMIT,
+        poa_unsupported_language_action: OMIT,
+        poa_address_mismatch_action: OMIT,
+        poa_issuer_not_identified_action: OMIT,
+        save_api_request: OMIT,
+        vendor_data: OMIT,
+        metadata: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/poa/",
+          body: {
+            "document" => document,
+            "document_password" => document_password,
+            "expected_address" => expected_address,
+            "expected_country" => expected_country,
+            "expected_first_name" => expected_first_name,
+            "expected_last_name" => expected_last_name,
+            "poa_languages_allowed" => poa_languages_allowed,
+            "poa_document_age_months" => poa_document_age_months,
+            "poa_name_mismatch_action" => poa_name_mismatch_action,
+            "poa_document_issues_action" => poa_document_issues_action,
+            "poa_document_authenticity_action" => poa_document_authenticity_action,
+            "poa_unsupported_language_action" => poa_unsupported_language_action,
+            "poa_address_mismatch_action" => poa_address_mismatch_action,
+            "poa_issuer_not_identified_action" => poa_issuer_not_identified_action,
+            "save_api_request" => save_api_request,
+            "vendor_data" => vendor_data,
+            "metadata" => metadata
+          },
+          encoding: :multipart,
+          file_fields: %w[document],
+          response: Types::ProofOfAddressVerifyResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end

data/lib/didit/resources/questionnaires.rb

@@ -0,0 +1,170 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +questionnaires+ resource.
+    class Questionnaires < Didit::Resource
+      # Create questionnaire
+      #
+      # Create a simple linear questionnaire. Send `form_elements` in display order; branching and repeatable groups
+      # require the Console. Defaults to `published` v1.
+      #
+      # +POST /v3/questionnaires/+
+      #
+      # @param title [String] Internal name for the questionnaire.
+      # @param languages [Array<String>] Languages included in every label. Must include `en`.
+      # @param form_elements [Array<Hash>] Questions in the exact order users should see them. Branching and
+      #   conditional fields are not supported.
+      # @param description [String, nil]
+      # @param default_language [String] Default language. Must be included in `languages`.
+      # @param is_active [Boolean]
+      # @param status [String] Omit this field to create a published questionnaire ready for workflows.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::QuestionnaireDetail]
+      def create(
+        title:,
+        languages:,
+        form_elements:,
+        description: OMIT,
+        default_language: OMIT,
+        is_active: OMIT,
+        status: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/questionnaires/",
+          body: {
+            "title" => title,
+            "languages" => languages,
+            "form_elements" => form_elements,
+            "description" => description,
+            "default_language" => default_language,
+            "is_active" => is_active,
+            "status" => status
+          },
+          response: Types::QuestionnaireDetail,
+          request_options: request_options
+        )
+      end
+
+      # Delete questionnaire
+      #
+      # Permanently delete one questionnaire version (no undo). Stored questionnaire responses linked to this version
+      # are deleted with it, and sessions referencing it lose the link; other versions in the same group are not
+      # deleted. Workflows that referenced it keep running but the questionnaire step can no longer load it.
+      #
+      # +DELETE /v3/questionnaires/{questionnaire_uuid}/+
+      #
+      # @param questionnaire_uuid [String] Per-version UUID of the questionnaire to delete.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [nil]
+      def delete(questionnaire_uuid, request_options: nil)
+        @client.request(
+          :delete,
+          "/v3/questionnaires/{questionnaire_uuid}/",
+          path_params: { "questionnaire_uuid" => questionnaire_uuid },
+          request_options: request_options
+        )
+      end
+
+      # List questionnaires
+      #
+      # List your questionnaires, newest first, in a limit/offset pagination envelope (`{count, next, previous,
+      # results}`, default page size 50). Each row is one version; `questionnaire_group_id` is the stable group ID
+      # resolved to the latest `published` version.
+      #
+      # +GET /v3/questionnaires/+
+      #
+      # @param limit [Integer] Page size (number of questionnaires per page).
+      # @param offset [Integer] Number of rows to skip before the first returned questionnaire.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Didit::Types::QuestionnaireListItem>]
+      def list(limit: OMIT, offset: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/questionnaires/",
+          query: {
+            "limit" => limit,
+            "offset" => offset
+          },
+          page: Types::QuestionnaireListItem,
+          request_options: request_options
+        )
+      end
+
+      # Get questionnaire
+      #
+      # Fetch full questionnaire detail for one version by `questionnaire_uuid`: title, `languages`, canonical
+      # `graph`, derived `sections`, and version metadata.
+      #
+      # +GET /v3/questionnaires/{questionnaire_uuid}/+
+      #
+      # @param questionnaire_uuid [String] Per-version UUID of the questionnaire (the `uuid` value returned by the
+      #   list endpoint, also returned as `questionnaire_id` on detail endpoints).
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::QuestionnaireDetail]
+      def retrieve(questionnaire_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/questionnaires/{questionnaire_uuid}/",
+          path_params: { "questionnaire_uuid" => questionnaire_uuid },
+          response: Types::QuestionnaireDetail,
+          request_options: request_options
+        )
+      end
+
+      # Update questionnaire
+      #
+      # Update a questionnaire. Versioning depends on the `status` field you send and the current state of the
+      # version: (1) no `status` on a **published** version → the published version is updated in place (same
+      # `questionnaire_id`, same `version`); (2) no `status` on a **draft** → the draft is updated and immediately
+      # published; (3) `status: "published"` on a **published** version → a NEW published version is created under the
+      # same `questionnaire_group_id` (new `questionnaire_id`, `version` + 1) and returned, and any existing draft in
+      # the group is deleted; (4) `status: "draft"` keeps a draft as a draft (autosave) but is rejected with 400 on a
+      # published version (`"Cannot revert a published version to draft."`).
+      #
+      # +PATCH /v3/questionnaires/{questionnaire_uuid}/+
+      #
+      # @param questionnaire_uuid [String] Per-version UUID of the questionnaire to update.
+      # @param title [String]
+      # @param description [String, nil]
+      # @param languages [Array<String>]
+      # @param default_language [String]
+      # @param is_active [Boolean]
+      # @param status [String]
+      # @param form_elements [Array<Hash>] If provided, this replaces the full linear question list.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::QuestionnaireDetail]
+      def update(
+        questionnaire_uuid,
+        title: OMIT,
+        description: OMIT,
+        languages: OMIT,
+        default_language: OMIT,
+        is_active: OMIT,
+        status: OMIT,
+        form_elements: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :patch,
+          "/v3/questionnaires/{questionnaire_uuid}/",
+          path_params: { "questionnaire_uuid" => questionnaire_uuid },
+          body: {
+            "title" => title,
+            "description" => description,
+            "languages" => languages,
+            "default_language" => default_language,
+            "is_active" => is_active,
+            "status" => status,
+            "form_elements" => form_elements
+          },
+          response: Types::QuestionnaireDetail,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end