Validate data

Run the same checks a render would run, without actually rendering — so you can surface problems to a user (or reject a submission) before spending a page credit. Validation consumes no render credit.

Endpoint

POST /v1/render/{templateId}/validate
POST /v1/render/{templateId}/versions/{version}/validate

Validate against the latest published version, or a specific one.

Example

cURL

curl -X POST "https://pagr-prd-api-public.azurewebsites.net/v1/render/8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90/validate" \
  -H "Authorization: Bearer pagr_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "Title": "Acme Q3 Invoice", "Amount": 42 }
    ]
  }'

Python

import asyncio
from pagr import PagrApiClient

async def main():
    async with PagrApiClient("pagr_test_xxxxxxxx") as client:
        result = await client.validate(
            "8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90",
            {"Title": "Acme Q3 Invoice", "Amount": 42},
        )

        if result.is_valid:
            print("Looks good")
        else:
            for issue in result.errors:      # blocking issues only
                print(issue)                 # "Error: MissingBinding [total] — …"
        for issue in result.warnings:        # allowed in test, blocking in production
            print("warning:", issue)

asyncio.run(main())

TypeScript

import { PagrApiClient } from 'pagr';

const client = new PagrApiClient('pagr_test_xxxxxxxx');

const result = await client.validate(
  '8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90',
  { Title: 'Acme Q3 Invoice', Amount: 42 },
);

if (result.isValid) {
  console.log('Looks good');
} else {
  for (const issue of result.errors) console.log(issue.description);
}
for (const issue of result.warnings) console.log('warning:', issue.description);

Java

import org.example.PagrApiClient;
import org.example.models.ValidationResponse;
import java.util.UUID;

try (PagrApiClient client = new PagrApiClient("pagr_test_xxxxxxxx")) {

    ValidationResponse result = client.validate(
        UUID.fromString("8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90"),
        "{\"Title\": \"Acme Q3 Invoice\", \"Amount\": 42}");

    if (result.isValid()) {
        System.out.println("Looks good");
    } else {
        result.getErrors().forEach(System.out::println);
    }
    result.getWarnings().forEach(w -> System.out.println("warning: " + w));
}

C#

using Pagr.Sdk;

using var client = new PagrApiClient("pagr_test_xxxxxxxx");

var result = await client.ValidateAsync(
    Guid.Parse("8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90"),
    new { Title = "Acme Q3 Invoice", Amount = 42 });

if (result.IsValid)
    Console.WriteLine("Looks good");
else
    foreach (var issue in result.Errors)
        Console.WriteLine(issue);

foreach (var issue in result.Warnings)
    Console.WriteLine($"warning: {issue}");

Ruby

require "pagr"

client = Pagr::Client.new("pagr_test_xxxxxxxx")

result = client.validate(
  "8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90",
  { "Title" => "Acme Q3 Invoice", "Amount" => 42 },
)

if result.valid?
  puts "Looks good"
else
  result.errors.each { |issue| warn issue }
end
result.warnings.each { |issue| warn "warning: #{issue}" }

C++

#include "pagr/PagrApiClient.hpp"

pagr::PagrApiClient client("pagr_test_xxxxxxxx");

auto result = client.validate(
    std::string("8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90"),
    R"({"Title": "Acme Q3 Invoice", "Amount": 42})");

if (result.is_valid()) {
    std::cout << "Looks good\n";
} else {
    for (const auto& issue : result.errors()) { /* handle */ }
}
for (const auto& issue : result.warnings()) { /* handle */ }

A validate_async form returning std::future<ValidationResponse> is also available.

Path parameters

Parameter	Type	Required	Description
templateId	string (UUID)	Yes	The template to validate against.
version	integer	Only for the specific-version form	The version number. Omit the whole segment to validate against the latest published version.

Query parameters

None. Validation has no persist or language parameter — it never produces output.

Request body

Field	Type	Required	Description
documents	array of objects	Yes	One object per document. Validate a batch in one call the same way you’d render one.

{
  "documents": [
    { "Title": "Acme Q3 Invoice", "Amount": 42 }
  ]
}

The SDKs accept a single document too

Pass one object and the SDK wraps it in the array for you; pass a list (or a JSON string encoding an array) and it’s treated as a batch. The wire format is always an array.

The Java SDK has no typed list overload for validate — pass a batch as a JSON string encoding an array ("[{…},{…}]"), or validate documents one at a time. Every other SDK accepts a native collection.

Response

Every call returns HTTP 200 with a flat list of issues across the whole batch:

{
  "issues": [
    {
      "type": "MissingBinding",
      "severity": "Error",
      "description": "No value bound for 'total'.",
      "elementId": "total-amount",
      "documentIndex": 0
    }
  ]
}

An empty issues array means every document is clean.

Issue fields

Field	Type	Description
type	string	The issue category — see Errors → Render issues for every value.
severity	string	Information, Warning, or Error.
description	string	Human-readable explanation. Don’t parse it; switch on type.
elementId	string or null	The template element the issue attaches to, when it maps to one.
documentIndex	number or null	Which document in the batch the issue belongs to. null for a batch-wide issue not scoped to one document.

is_valid already matches production — not test/preview

TODO: has changed. Should now be more logical

is_valid is false as soon as any issue is Warning or Error severity — the same gate a production render applies. But the two rendering environments differ:

• Production rendering blocks on Warning and Error.
• Test / preview rendering blocks only on Error.

So a result with only warnings comes back is_valid: false even though it would still render fine on a test key. If you only ever render with test keys, check errors directly instead — see Renders → Test vs Production.

SDK reference

SDK	Method	Result accessors
Python	await client.validate(template_id, json_data, *, version=None)	.is_valid, .errors, .warnings, .issues_for(i), iterable
TypeScript	await client.validate(templateId, data, { version })	.isValid, .errors, .warnings, .issuesFor(i), iterable
Java	client.validate(templateId, data[, version]) — data is a JSON String, JsonObject or Map	.isValid(), .getErrors(), .getWarnings(), .issuesFor(i), iterable
C#	await client.ValidateAsync(templateId, data, version, cancellationToken)	.IsValid, .Errors, .Warnings, .IssuesFor(i), IReadOnlyList<RenderIssue>
Ruby	client.validate(template_id, json_data, version:)	.valid?, .errors, .warnings, .issues_for(i), Enumerable
C++	client.validate(template_id, json_data, version) / validate_async(…)	.is_valid(), .errors(), .warnings(), .issues_for(i)

issues_for(i) returns the issues for document i plus every batch-wide issue (those whose documentIndex is null) — so a per-document error report is never missing a batch-level cause.

Errors

Status	code	When
404	TemplateNotFound, VersionNotFound, NoPublishedVersion	The template or version doesn’t exist, or nothing is published yet.
422	BindingError	The request body couldn’t be parsed or bound.

See Errors for the full table.

Related articles

• Validate before rendering — the validate-then-render pattern, step by step.
• Render a document — the endpoint this mirrors.
• Errors → Render issues — the full issue type table with severities.
• Templates & versions — fetch a version’s sampleData as a validation starting point.