Sandbox mock data

Overview

In sandbox, when you create a KYC validation for a person entity, the API can return an immediate mock result based on the entity’s taxId (document number). No external verification is performed; the response and webhooks match the outcome associated with that document in our test set. This lets you test all flows (approved, rejected, cancelled, RENAPER double-check, etc.) without going through a real verification.

Configure a webhook to receive responses!In sandbox, KYC results are updated asynchronously (same as production). While the API returns 201 immediately after creating the validation, the final result (approved, rejected, etc.) is sent via webhooks moments later.You must configure a webhook endpoint in your organization to receive validation notifications. Without a configured webhook, you won’t receive status updates.📚 Learn to set up webhooks: Webhook integration

Format does not matter. The entity’s taxId can be sent with or without formatting (e.g. 99.990.001 or 99990001). The API normalizes it before matching, so both work the same.

How It Works

The person entity belongs to an organization that is in sandbox mode.
You call POST /api/kyc/validations with that entity’s entityId.
The API looks up the entity’s taxId in the sandbox test map (after normalizing: digits and letters only).
If there is a match, a mock validation is created with pending status (201 Created) and moments later it’s updated to the final status (e.g. approved, rejected, cancelled).
Webhooks are sent to your configured endpoint with the final result.
If there is no match, the API follows the normal flow (creates a real verification session and returns providerSessionUrl).

Asynchronous flow: The sandbox behavior exactly replicates the production flow, which is asynchronous. The validation is created in pending state, then updated and notified via webhook. Do not attempt immediate polling to the GET endpoint after creating the validation - use webhooks to receive the result.

Synthetic Entity Preview (GET Only)

In sandbox, when you look up a catalog test document number and no real entity row exists, Gu1 can return a synthetic person instead of 404:

GET /api/entities/by-tax-id/{taxId}
GET /api/entities?taxId={taxId} (exact filter, zero real matches)

Response includes sandboxMock: true, id: null, and metadata.sandboxKycOutcome (expected KYC mock outcome for that number). Nothing is written to the database.

The synthetic preview is for discovery and documentation. To run POST /api/kyc/validations or POST /api/kyc/biometric/sessions with entityTaxId, you must create a real person entity first (same test taxId). KYC/biometric endpoints resolve against persisted rows only.

RENAPER in sandbox: If you send doubleCheckRenaper: true when creating the validation and the outcome is approved (or a RENAPER-related rejection), the response and webhook payload will include metadata.responseDoubleChecks.renaper with the same structure as in production.

Default Test Values

We provide a fixed set of test document numbers in four formats. Each number maps to one outcome. The lookup key is the normalized value (no dots, dashes, or spaces).

Outcome List (What Each Number Returns)

#	Outcome	Result
01	`approved`	KYC approved. If you requested RENAPER double-check, the response includes RENAPER success.
02	`approved_with_renaper`	Same as approved; RENAPER in the response only if requested in the creation.
03	`cancelled`	Validation cancelled.
04	`rejected`	Generic rejection.
05	`rejected_document_mismatch`	Rejection due to document number not matching the entity.
06	`rejected_renaper_tramite_not_match`	Rejection: transaction number does not match registry.
07	`rejected_renaper_dni_not_match`	Rejection: document number does not match registry.
08	`rejected_renaper_verification_unavailable`	Rejection: registry verification unavailable.
09	`rejected_renaper_dni_missing`	Rejection: no document number available for registry check.
10	`rejected`	Generic rejection (second number for testing).

Argentina – DNI (8 digits)

Use any of these as the entity’s taxId (with or without dots). Normalized value is used for matching.

Example value	Normalized	Outcome
99.990.001 or 99990001	99990001	approved
99.990.002 or 99990002	99990002	approved_with_renaper
99.990.003	99990003	cancelled
99.990.004	99990004	rejected
99.990.005	99990005	rejected_document_mismatch
99.990.006	99990006	rejected_renaper_tramite_not_match
99.990.007	99990007	rejected_renaper_dni_not_match
99.990.008	99990008	rejected_renaper_verification_unavailable
99.990.009	99990009	rejected_renaper_dni_missing
99.990.010	99990010	rejected
99.990.011	99990011	approved (KYC); biometric mock defaults to rejected — see Embedded biometric mock

Argentina – CUIT (11 digits)

Format: 20-XXXXXXXX-X. Example: 20-99990001-9.

Example value	Normalized	Outcome
20-99990001-9	20999900019	approved
20-99990002-9	20999900029	approved_with_renaper
20-99990003-9	20999900039	cancelled
20-99990004-9	20999900049	rejected
20-99990005-9	20999900059	rejected_document_mismatch
20-99990006-9	20999900069	rejected_renaper_tramite_not_match
20-99990007-9	20999900079	rejected_renaper_dni_not_match
20-99990008-9	20999900089	rejected_renaper_verification_unavailable
20-99990009-9	20999900099	rejected_renaper_dni_missing
20-99990010-9	20999900109	rejected
20-99990011-9	20999900119	approved (KYC); biometric mock defaults to rejected

Brazil – CPF (11 digits)

Format: XXX.XXX.XXX-XX. Example: 999.900.001-01.

Example value	Normalized	Outcome
999.900.001-01	99990000101	approved
999.900.001-02	99990000102	approved_with_renaper
999.900.001-03	99990000103	cancelled
999.900.001-04	99990000104	rejected
999.900.001-05	99990000105	rejected_document_mismatch
999.900.001-06	99990000106	rejected_renaper_tramite_not_match
999.900.001-07	99990000107	rejected_renaper_dni_not_match
999.900.001-08	99990000108	rejected_renaper_verification_unavailable
999.900.001-09	99990000109	rejected_renaper_dni_missing
999.900.001-10	99990000110	rejected

Brazil – CNPJ (14 digits)

Format: XX.XXX.XXX/XXXX-XX. Example: 99.990.000/0001-01.

Example value	Normalized	Outcome
99.990.000/0001-01	99990000000101	approved
99.990.000/0001-02	99990000000102	approved_with_renaper
99.990.000/0001-03	99990000000103	cancelled
99.990.000/0001-04	99990000000104	rejected
99.990.000/0001-05	99990000000105	rejected_document_mismatch
99.990.000/0001-06	99990000000106	rejected_renaper_tramite_not_match
99.990.000/0001-07	99990000000107	rejected_renaper_dni_not_match
99.990.000/0001-08	99990000000108	rejected_renaper_verification_unavailable
99.990.000/0001-09	99990000000109	rejected_renaper_dni_missing
99.990.000/0001-10	99990000000110	rejected

Example: Approved with RENAPER

Create a person entity in sandbox with taxId: 99990001 (or 99.990.001).
Call POST /api/kyc/validations with entityId and doubleCheckRenaper: true (body or query).
The API returns 201 with the validation; shortly after, the status is approved and the webhook kyc.validation_approved is sent.
The webhook payload includes the full validation object, including metadata.responseDoubleChecks.renaper with verified: true, matchResult: "match", personalNumber, idTramitePrincipal, and renaperData (mock registry response).

Example Response (Mock Approved)

The response body and webhook payload follow the same structure as a real validation. Example shape for an approved mock (relevant fields):

{
  "id": "uuid",
  "entityId": "uuid",
  "status": "approved",
  "verifiedAt": "2026-02-21T12:00:00.000Z",
  "extractedData": {
    "firstName": "Sandbox",
    "lastName": "User",
    "fullName": "Sandbox User",
    "dateOfBirth": "1990-01-15",
    "documentNumber": "99990001",
    "documentType": "Identity Card",
    "nationality": "AR",
    "gender": "M",
    "ejemplar": "A",
    "age": 34
  },
  "verifiedFields": ["identity_document", "liveness_check", "face_match"],
  "warnings": [],
  "metadata": {
    "doubleChecks": { "renaper": true },
    "responseDoubleChecks": {
      "renaper": {
        "verified": true,
        "matchResult": "match",
        "personalNumber": "99990001",
        "idTramitePrincipal": "987654321",
        "verifiedAt": "2026-02-21T12:00:00.000Z",
        "comparisonResults": {
          "dni": { "field": "dni", "compared": true, "passed": true, "ocrValue": "99990001", "renaperValue": "99990001" },
          "tramite": { "field": "tramite", "compared": true, "passed": true, "ocrValue": "99990001", "renaperValue": "987654321" },
          "ejemplar": { "field": "ejemplar", "compared": true, "passed": true, "ocrValue": "A", "renaperValue": "A" }
        },
        "renaperData": {
          "id_tramite_principal": "987654321",
          "id_tramite_tarjeta_reimpresa": "112233445",
          "ejemplar": "A",
          "vencimiento": "2030-05-20",
          "emision": "2015-05-20",
          "apellido": "User",
          "nombres": "Sandbox",
          "fecha_nacimiento": "1990-01-15",
          "cuil": "20-99990001-9",
          "calle": "Av. Corrientes",
          "numero": "1234",
          "piso": "5",
          "departamento": "B",
          "codigo_postal": "1043",
          "barrio": "San Nicolás",
          "monoblock": "",
          "ciudad": "Ciudad Autónoma de Buenos Aires",
          "municipio": "Comuna 1",
          "provincia": "Buenos Aires",
          "pais": "Argentina",
          "nacionalidad": "Argentina",
          "codigo_fallecido": "",
          "mensaje_fallecido": "",
          "fecha_fallecimiento": "",
          "id_ciudadano": "99990001",
          "codigo": "",
          "mensaje": ""
        }
      }
    }
  }
}

When RENAPER double-check is not requested, metadata.responseDoubleChecks is not present for approved; when it is requested, it is present as above. For renaperData on rejections or service errors, see renaperData shape.

Embedded Biometric (Sandbox Mock)

After an approved KYC mock for the same entity, you can create an embedded biometric session (POST /api/kyc/biometric/sessions) that also runs in mock mode in sandbox—no hosted capture UI; Gu1 returns the result immediately.

Mock biometric uses the same sandbox organization and same test taxId map as KYC mock. Validations created via mock include metadata.sandboxMock: true. Biometric sessions created via mock include metadata.sandboxMock: true and metadata.sandboxMockOutcome (approved or rejected).

Prerequisites

Organization in sandbox mode (same as KYC mock).
Person entity with a test taxId whose KYC outcome is approved or approved_with_renaper (e.g. 99990001, 99990002, 99990011).
Approved KYC for that entity (create via POST /api/kyc/validations first).

Default Biometric Outcomes by Test Document

Example `taxId`	Normalized	KYC mock	Biometric mock (default)
99990001 / 20-99990001-9	99990001 / 20999900019	approved	approved (immediate)
99990002 / 20-99990002-9	99990002 / 20999900029	approved_with_renaper	approved (immediate)
99990011 / 20-99990011-9	99990011 / 20999900119	approved	rejected (immediate)

For documents whose KYC mock is rejected or cancelled, you cannot create a biometric session (NO_KYC).

Override Outcome on the Same Entity

On any eligible mock entity, send metadata.sandboxMockOutcome in the create body:

POST /api/kyc/biometric/sessions
{
  "entityId": "uuid",
  "metadata": {
    "sandboxMockOutcome": "rejected"
  }
}

Allowed values: approved, rejected. This only applies when the request qualifies for sandbox mock (sandbox org + approved KYC mock, or metadata.sandboxMock: true on the source KYC).

Example: Mock Approved

Create person entity with taxId: 99990001.
POST /api/kyc/validations → wait for webhook kyc.validation_approved (or poll GET until approved).
POST /api/kyc/biometric/sessions with { "entityId": "..." }.

Response 201:

{
  "id": "uuid",
  "entityId": "uuid",
  "status": "approved",
  "sessionUrl": "https://kyc-v2-onboarding.gueno.io/session/sandbox-mock-bio-...",
  "hostedSessionId": "sandbox-mock-bio-...",
  "mode": "face_match",
  "iframeAllow": "camera; microphone; fullscreen; autoplay; encrypted-media"
}

Webhooks: biometric.session_approved (org webhook and optional per-request webhookUrl). No iframe step is required for mock sessions.

Example: Mock Rejected

Option A — dedicated test document 99990011 (KYC approved, biometric rejected by default). Option B — same entity as 99990001 with "metadata": { "sandboxMockOutcome": "rejected" }. Response status is rejected; webhook event is biometric.session_rejected.

Real (Non-Mock) Biometric in Sandbox

If the entity taxId is not in the test map, or the organization is not sandbox, POST /api/kyc/biometric/sessions follows the production path: hosted capture UI, status: pending, and a Gu1-assigned hostedSessionId. Requires a valid reference portrait from approved KYC.

Retries and Active Sessions

If the latest biometric session for the entity is still pending or in_progress, create returns 409 ACTIVE_SESSION_EXISTS with activeSessionId. Cancel it with POST /api/kyc/biometric/sessions/:id/cancel before creating another.
If a previous create succeeded but your client retried, Gu1 reuses the existing row when the same hostedSessionId is returned (idempotent create).

Custom Mock Data

The default set above is available to all sandbox organizations with no configuration.

Adding or changing mock document numbers for your sandbox:
If you need additional test documents or different outcomes for specific numbers, contact the Gu1 team. Custom mock data for sandbox is managed by Gu1 and cannot be configured by the client.

​Overview

​How It Works

​Synthetic Entity Preview (GET Only)

​Default Test Values

​Outcome List (What Each Number Returns)

​Argentina – DNI (8 digits)

​Argentina – CUIT (11 digits)

​Brazil – CPF (11 digits)

​Brazil – CNPJ (14 digits)

​Example: Approved with RENAPER

​Example Response (Mock Approved)

​Embedded Biometric (Sandbox Mock)

​Prerequisites

​Default Biometric Outcomes by Test Document

​Override Outcome on the Same Entity

​Example: Mock Approved

​Example: Mock Rejected

​Real (Non-Mock) Biometric in Sandbox

​Retries and Active Sessions

​Custom Mock Data

​See Also

Overview

How It Works

Synthetic Entity Preview (GET Only)

Default Test Values

Outcome List (What Each Number Returns)

Argentina – DNI (8 digits)

Argentina – CUIT (11 digits)

Brazil – CPF (11 digits)

Brazil – CNPJ (14 digits)

Example: Approved with RENAPER

Example Response (Mock Approved)

Embedded Biometric (Sandbox Mock)

Prerequisites

Default Biometric Outcomes by Test Document

Override Outcome on the Same Entity

Example: Mock Approved

Example: Mock Rejected

Real (Non-Mock) Biometric in Sandbox

Retries and Active Sessions

Custom Mock Data

See Also