Skip to main content

​
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

  1. The person entity belongs to an organization that is in sandbox mode.
  2. You call POST /api/kyc/validations with that entity’s entityId.
  3. The API looks up the entity’s taxId in the sandbox test map (after normalizing: digits and letters only).
  4. 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).
  5. Webhooks are sent to your configured endpoint with the final result.
  6. 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. 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)

#OutcomeResult
01approvedKYC approved. If you requested RENAPER double-check, the response includes RENAPER success.
02approved_with_renaperSame as approved; RENAPER in the response only if requested in the creation.
03cancelledValidation cancelled.
04rejectedGeneric rejection.
05rejected_document_mismatchRejection due to document number not matching the entity.
06rejected_renaper_tramite_not_matchRejection: transaction number does not match registry.
07rejected_renaper_dni_not_matchRejection: document number does not match registry.
08rejected_renaper_verification_unavailableRejection: registry verification unavailable.
09rejected_renaper_dni_missingRejection: no document number available for registry check.
10rejectedGeneric 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 valueNormalizedOutcome
99.990.001 or 9999000199990001approved
99.990.002 or 9999000299990002approved_with_renaper
99.990.00399990003cancelled
99.990.00499990004rejected
99.990.00599990005rejected_document_mismatch
99.990.00699990006rejected_renaper_tramite_not_match
99.990.00799990007rejected_renaper_dni_not_match
99.990.00899990008rejected_renaper_verification_unavailable
99.990.00999990009rejected_renaper_dni_missing
99.990.01099990010rejected

​
Argentina – CUIT (11 digits)

Format: 20-XXXXXXXX-X. Example: 20-99990001-9.
Example valueNormalizedOutcome
20-99990001-920999900019approved
20-99990002-920999900029approved_with_renaper
20-99990003-920999900039cancelled
20-99990004-920999900049rejected
20-99990005-920999900059rejected_document_mismatch
20-99990006-920999900069rejected_renaper_tramite_not_match
20-99990007-920999900079rejected_renaper_dni_not_match
20-99990008-920999900089rejected_renaper_verification_unavailable
20-99990009-920999900099rejected_renaper_dni_missing
20-99990010-920999900109rejected

​
Brazil – CPF (11 digits)

Format: XXX.XXX.XXX-XX. Example: 999.900.001-01.
Example valueNormalizedOutcome
999.900.001-0199990000101approved
999.900.001-0299990000102approved_with_renaper
999.900.001-0399990000103cancelled
999.900.001-0499990000104rejected
999.900.001-0599990000105rejected_document_mismatch
999.900.001-0699990000106rejected_renaper_tramite_not_match
999.900.001-0799990000107rejected_renaper_dni_not_match
999.900.001-0899990000108rejected_renaper_verification_unavailable
999.900.001-0999990000109rejected_renaper_dni_missing
999.900.001-1099990000110rejected

​
Brazil – CNPJ (14 digits)

Format: XX.XXX.XXX/XXXX-XX. Example: 99.990.000/0001-01.
Example valueNormalizedOutcome
99.990.000/0001-0199990000000101approved
99.990.000/0001-0299990000000102approved_with_renaper
99.990.000/0001-0399990000000103cancelled
99.990.000/0001-0499990000000104rejected
99.990.000/0001-0599990000000105rejected_document_mismatch
99.990.000/0001-0699990000000106rejected_renaper_tramite_not_match
99.990.000/0001-0799990000000107rejected_renaper_dni_not_match
99.990.000/0001-0899990000000108rejected_renaper_verification_unavailable
99.990.000/0001-0999990000000109rejected_renaper_dni_missing
99.990.000/0001-1099990000000110rejected

​
Example: Approved with RENAPER

  1. Create a person entity in sandbox with taxId: 99990001 (or 99.990.001).
  2. Call POST /api/kyc/validations with entityId and doubleCheckRenaper: true (body or query).
  3. The API returns 201 with the validation; shortly after, the status is approved and the webhook kyc.validation_approved is sent.
  4. 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.

​
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.

​
See Also