---
updatedAt: 2026-09-16T20:15:51.000Z
agentTools:
  projectIndex: https://docs.dlocal.com/llms.txt
---

# Update verification state (sandbox only)

**Sandbox only.** Changes verification status while preserving realistic flow transitions, so you can simulate states and receive notifications.

Official reference uses host `sandbox.dlocal.com` and path `/kyc/sandbox-tools/verifications/{verification-id}`.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "KYC Verifications",
    "version": "1.0.0",
    "license": {
      "name": "Proprietary"
    },
    "description": "KYC Verifications API — create and manage verifications (remittances, payouts on hold, payins on hold, standalone, etc.).\nMandatory fields depend on client type, country, and industry. The verification ID returned is used across Payins and Payouts flows.\n**Environments (from product reference)**  \n**Production:** `https://api.dlocal.com/kyc`  \n**Sandbox:** `https://kyc.dlocal-sbox.com` (paths in this spec are relative to these base URLs).\n**Standard error body** (all KYC error responses use this shape):\n`code`, `message`, and optional `field` (parameter related to the error). See `KycError` and the error codes listed under that schema.\n**Pagination** (list responses such as “get documents”): `items`, `current_page`, `total_pages`, `page_size`, `total`.\nPublic API reference: [Create a verification](https://docs.dlocal.com/reference/create-verification), [Get verification](https://docs.dlocal.com/reference/get-verification), [Get documents](https://docs.dlocal.com/reference/get-verification-documents), [Update document](https://docs.dlocal.com/reference/update-verification-document), [Update verification state (sandbox)](https://docs.dlocal.com/reference/update-verification-state).\n"
  },
  "security": [
    {
      "X-Date": [],
      "X-Login": [],
      "X-Trans-Key": [],
      "Authorization": []
    }
  ],
  "x-explorer-enabled": false,
  "x-proxy-enabled": false,
  "x-samples-languages": [
    "curl"
  ],
  "servers": [
    {
      "url": "https://api.dlocal.com/kyc",
      "description": "Production"
    },
    {
      "url": "https://kyc.dlocal-sbox.com",
      "description": "Sandbox"
    }
  ],
  "tags": [
    {
      "name": "Sandbox tools",
      "description": "Sandbox-only utilities to simulate verification state transitions and notifications."
    }
  ],
  "paths": {
    "/sandbox-tools/verifications/{verification-id}": {
      "servers": [
        {
          "url": "https://sandbox.dlocal.com/kyc",
          "description": "Sandbox — state simulation (path spelling matches API)"
        }
      ],
      "patch": {
        "tags": [
          "Sandbox tools"
        ],
        "summary": "Update verification state (sandbox only)",
        "operationId": "update-verification-state",
        "description": "**Sandbox only.** Changes verification status while preserving realistic flow transitions, so you can simulate states and receive notifications.\n\nOfficial reference uses host `sandbox.dlocal.com` and path `/kyc/sandbox-tools/verifications/{verification-id}`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/VerificationId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status",
                  "status_detail"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "description": "Target verification status. [See details](https://docs.dlocal.com/reference/verification-status)."
                  },
                  "status_detail": {
                    "type": "string",
                    "description": "Target status detail. [See details](https://docs.dlocal.com/reference/verification-status)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event processed successfully"
          },
          "400": {
            "description": "Bad request — invalid verification status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KycError"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KycError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — authentication failed or unauthorized access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KycError"
                }
              }
            }
          },
          "404": {
            "description": "Verification not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KycError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KycError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "VerificationId": {
        "name": "verification-id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "dLocal verification ID in UUID format."
      }
    },
    "securitySchemes": {
      "X-Date": {
        "type": "apiKey",
        "name": "X-Date",
        "in": "header",
        "description": "ISO-8601 datetime with timezone (e.g. `2018-07-12T13:46:28.629Z`)."
      },
      "X-Login": {
        "type": "apiKey",
        "name": "X-Login",
        "in": "header",
        "description": "Merchant login identifier."
      },
      "X-Trans-Key": {
        "type": "apiKey",
        "name": "X-Trans-Key",
        "in": "header",
        "description": "Transaction key (with `X-Login`) for authentication."
      },
      "Authorization": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "description": "Signature header: `V2-HMAC-SHA256, Signature: {signature}` where the signature is HMAC-SHA256 of `X-Login+X-Date+RequestBody` with your secret key.\n"
      }
    },
    "schemas": {
      "KycError": {
        "type": "object",
        "description": "Standard error envelope for the KYC Verifications API. Typical `code` values (non-exhaustive, per product reference):\n**Generic:** `invalid_verification_status` (400), `internal_error` (500), `unauthorized` / `authentication_failed` (403), `invalid_credentials` (401).\n**Verifications:** `verification_not_found` (404) — `field` may be `verification_id`.\n**Documents:** `document_not_found` (404) — `field` may be `document_id`.\n**Create / file upload:** `invalid_format` (400) — e.g. `client.date_of_birth` in `field`;\n`file_format_not_supported`, `unsupported_mime_type`, `file_too_large` (max 10 MB per file), `file_empty` — often with `file` or `file_name` in `field` when applicable.\n",
        "example": {
          "code": "invalid_format",
          "message": "Invalid format.",
          "field": "client.date_of_birth"
        },
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable description."
          },
          "field": {
            "type": "string",
            "description": "Parameter or field name associated with the error, when applicable."
          }
        }
      }
    }
  }
}
```