ValidConvert API usage guide

Swagger is intentionally read-only. Try it out is disabled and authorization is never persisted. Examples below use placeholders only.

Quick examples

Get converters

curl https://api.validconvert.com/v1/converters

Browser session: CSRF and login

curl -c vc-cookies.txt https://api.validconvert.com/v1/auth/csrf

curl -b vc-cookies.txt -c vc-cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: <CSRF_TOKEN>" \
  -d '{"email":"[email protected]","password":"<PASSWORD>"}' \
  https://api.validconvert.com/v1/auth/login

If adaptive login protection responds with VC_TURNSTILE_REQUIRED, obtain a fresh Turnstile token for action login_challenge and retry with X-ValidConvert-Turnstile-Token: <TURNSTILE_TOKEN>.

Create an API key

curl -b vc-cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: <CSRF_TOKEN>" \
  -H "Idempotency-Key: 0afde9dd-3643-44b2-9164-9cd4a155cb5b" \
  -d '{}' \
  https://api.validconvert.com/v1/account/api-key

The API-key secret is returned once. Store it securely; it cannot be recovered later.

API conversion

curl --data-binary @statement.xml \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/octet-stream" \
  -H "Idempotency-Key: 0afde9dd-3643-44b2-9164-9cd4a155cb5b" \
  -H "X-ValidConvert-Input-Bytes: <EXACT_DECIMAL_BYTES>" \
  "https://api.validconvert.com/v1/conversions?converter_id=camt053-to-mt940&converter_version=1" \
  --output statement.mt940

Replay the same logical request with the same Idempotency-Key. A successful replay does not debit credits again while the retained result remains available.

Get balance

curl -H "Authorization: Bearer <API_KEY>" https://api.validconvert.com/v1/credits/balance

Create checkout and read purchase

curl -b vc-cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: <CSRF_TOKEN>" \
  -H "Idempotency-Key: 2f7583dc-b8ff-4bb4-970f-9ae80e6a9df4" \
  -d '{"pack_id":"STANDARD"}' \
  https://api.validconvert.com/v1/billing/checkout-sessions

curl -b vc-cookies.txt https://api.validconvert.com/v1/billing/purchases/pur_<UUID>

PowerShell binary upload

$headers = @{
  Authorization = "Bearer <API_KEY>"
  "Idempotency-Key" = "0afde9dd-3643-44b2-9164-9cd4a155cb5b"
  "X-ValidConvert-Input-Bytes" = (Get-Item .\statement.xml).Length.ToString()
}
Invoke-WebRequest \
  -Uri "https://api.validconvert.com/v1/conversions?converter_id=camt053-to-mt940&converter_version=1" \
  -Method Post \
  -Headers $headers \
  -ContentType "application/octet-stream" \
  -InFile .\statement.xml \
  -OutFile .\statement.mt940

For browser-session calls in PowerShell, keep the same WebRequestSession for cookies and send the current X-CSRF-TOKEN on state-changing requests.

Conversion limits and credit cost

Trial input is limited to 10,000,000 decimal bytes and 10,000 transactions. Paid web/API input is limited to 50,000,000 decimal bytes and 50,000 transactions. Successful conversion output is capped at 100,000,000 decimal bytes.

Paid CAMT053-to-MT940 V1 cost is max(1, ceil(input_bytes / 10,000,000)) credits: 1-10,000,000 bytes = 1 credit; 10,000,001-20,000,000 = 2; 20,000,001-30,000,000 = 3; 30,000,001-40,000,000 = 4; 40,000,001-50,000,000 = 5.

Successful encrypted output is retained privately for idempotent replay for up to 24 hours; the original input is not retained after processing.

Authentication lifetimes

Email-verification tokens expire after 24 hours. Password-reset tokens expire after 30 minutes and are one-use. Web sessions expire after 30 minutes of inactivity and have a 12-hour absolute lifetime; recent authentication is valid for 10 minutes.

API usage

Supported technical uses include internal automation, processing accounting/professional client files, ERP integrations where ValidConvert is a secondary function, and legitimate server-to-server automation.

Without a separate agreement, do not expose an API key, resell API access or credits, operate a generic public proxy whose backend is primarily ValidConvert, or present ValidConvert as a white-label service.

Browser origin and server-to-server clients

The production browser frontend origin is exactly https://validconvert.com. There is no wildcard, Origin: null allowance, or implicit arbitrary-subdomain allowance. CORS is a browser policy, not authentication.

Server-to-server Bearer clients do not need an Origin header.

Errors and versioning

Machine-readable errors use application/problem+json. Unknown paths return 404 VC_NOT_FOUND; unsupported HTTP methods return 405 VC_METHOD_NOT_ALLOWED, never an HTML error page. See the error catalog. The public API remains under /v1; OpenAPI document version 3.2.1 is independent from ValidConvert API version 1.0.0.

Within V1, removing or renaming fields, changing field types or authentication, adding a required parameter, changing idempotency or economic semantics, or reducing a contractual guarantee is a breaking change and requires a new API version when applicable. Optional fields or endpoints, new converters or converter versions, and higher limits may be compatible additions depending on the change. V1 is the active initial API and is not deprecated or under a sunset policy.