Conventions

Versioning

Every v2 response carries X-RandaVerify-Version. Additive changes (a new field, a new error code, a new endpoint) can happen without notice, so parse leniently and ignore what you do not recognise. Anything that would break a correct integration gets a new version and 90 days’ notice, as the service agreement says.

JSON or XML

JSON by default. For XML, either negotiate it:

curl https://api.randaverify.com/v2/verify/REF-AB58AB785AD4 \
  -H "Authorization: Bearer rv_live_..." \
  -H "Accept: application/xml"

or ask explicitly with ?format=xml, which is easier from tools where you cannot set headers.

The data is identical in both. The mapping is:

{"a": 1}           <response><a>1</a></response>
{"a": {"b": 2}}    <response><a><b>2</b></a></response>
{"a": [1, 2]}      <response><a><item>1</item><item>2</item></a></response>
{"a": null}        <response><a/></response>
{"a": true}        <response><a>true</a></response>

Errors are available in XML too, so you do not need two parsers.

Rate limits

Per organisation, not per key, and shared across our workers, so the advertised limit is the real one. Every response carries:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Exceeding it is 429 with rate_limited, which is retryable. If your volumes need a higher limit, ask: it is a per-organisation setting.

Headers at a glance

Header	Direction	Purpose
`Authorization`	Request	`Bearer` plus an API key or an access token
`Idempotency-Key`	Request	Makes a retry safe for 24 hours
`Accept`	Request	`application/json` or `application/xml`
`X-RV-Timestamp`, `X-RV-Nonce`, `X-RV-Signature`	Request	Request signing, when enabled
`X-Request-Id`	Response	Quote this to support
`X-RandaVerify-Version`	Response	The contract version
`Idempotent-Replay`	Response	`true` when you received a stored answer

The machine-readable specification

/v2/openapi.json is generated from the running service, not maintained by hand, so it cannot describe an endpoint that does not exist or miss one that does. Point your client generator at it.