The CreditRefPro API

A versioned, organization-scoped REST API under /v1. Everything on this page is read from the running implementation — the endpoints from the router, the scopes and errors from their own catalogues, the rate limits from the same settings the limiter reads. There is no separate document to fall out of date.

The same thing as JSON: /developers.json.

Authentication

OAuth 2.0

POST /v1/oauth/token, grant client_credentials. Tokens last 60 minutes. Send your key id and secret, get a short-lived token. A token may ask for a subset of your client's scopes and never more, and the narrower of the two always wins — so trimming a client narrows tokens already issued.

API key

Authorization: Bearer <key_id>:<secret>. For a batch job that makes one call a night and should not have to run a token exchange to make it.

Transport

The Authorization header only. A credential in a query string ends up in access logs, browser history and referrer headers.

Revocation

Revoking a client revokes every token it issued, in the same statement. A key revoked at four whose token works until five has not been revoked.

Rate limits

Your organization's metered API usage under the api_calls pricing rule. The band you are billed in is the band you are limited in. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Tier, Retry-After.

Pagination

Every collection returns {data, page: {limit, has_more, next_cursor}}. Pass next_cursor back as cursor. Cursors are opaque: do not construct or parse one. Default 25, maximum 100.

Idempotency

Idempotency-Key on every state-changing endpoint, marked in the endpoint list. A repeat of the same key and the same body returns the original response, byte for byte. The same key with a different body is refused rather than answered, because it means your code reused a key and handing you the earlier result would have you believe a request succeeded that was never made. Only successful writes are remembered. Remembered for 24 hours.

Scopes

Endpoints

Errors

Every failure has a stable machine-readable code and a fixed sentence. The message never names a record, an organization or an identifier: a record that does not exist and one that is not yours answer identically, because telling them apart would confirm the existence of records a caller has no business knowing about. A request_id comes back on every error so a support conversation can happen without anybody quoting data.

Webhooks

A delivery carries an event id, the event name, the type and id of the object, and a link. It carries no borrower data. Fetch the object through the API, where your scope and the borrower's own permissions are applied at the moment you read — a payload rendered when the event happened could otherwise carry data whose permission was withdrawn before it was delivered.

Verifying a delivery

Signed content is <timestamp>.<nonce>.<raw body>, using HMAC-SHA256 with your endpoint secret. Timestamps outside 300 seconds are stale.

Compute the HMAC over the raw body you received, not over a body you parsed and re-serialised. Compare in constant time. Reject a timestamp outside the tolerance, and reject a nonce you have seen before — a replayed delivery carries a valid signature, which is what makes it a replay.

X-CreditRefPro-Signature

v1=<hex hmac-sha256>

X-CreditRefPro-Timestamp

seconds since the epoch, as we saw it

X-CreditRefPro-Nonce

single-use, per delivery

X-CreditRefPro-Event

the event name, so you can route without parsing

X-CreditRefPro-Attempt

which attempt this is

Retries

6 attempts, at 0s, 60s, 300s, 1800s, 7200s, 21600s after the first. Any 2xx. Answer quickly and do the work afterwards; we give up waiting after 10 seconds and will retry.

Disabled after 20 consecutive failures, and we tell you when that happens.

Pushing to us

If you push to us, sign it the same way with the secret an administrator configured for your provider record. Unsigned or invalid deliveries are refused and logged; a nonce we have seen is refused whether or not its signature is good.

Sandbox

What it is

Your organization can have a sandbox: a separate organization holding synthetic borrowers, requests and facilities, with its own keys and its own webhook endpoints.

Separation

A sandbox key reaches sandbox records and nothing else. The separation is the same one that stops one lender reading another's rows, rather than a second mechanism layered on top — and a key whose environment disagrees with its organization is refused before any handler runs.

The data

Synthetic records are built through the same code paths real ones are, so they behave the same way. Names are prefixed, and addresses use a domain that cannot receive mail.

Webhooks

A sandbox endpoint hears sandbox events only. A test run will not page whoever is on call for production.

Worked examples