Transport for the Sumsub API: App Token request signing, JSON and
multipart bodies that never send unset fields, path and query
encoding, Sumsub's error object lifted into HttpError, and the
offset pagination used by list endpoints.
Error messages never include request data or Sumsub's description
(which can echo submitted values); they carry the status, Sumsub's
numeric errorCode/errorName and the correlationId to quote to
Sumsub support.
Per-call credentials. Every API-calling function has a trailing
opts Map, resolved by resolve: opts first, then context, then
defaults. Nothing from opts is written to context, so one run can
act for many tenants, and per-call credentials are masked in call
records. app-token and secret-key come as a pair; either one
present but blank or null is an error, never a fallback to context. A
per-call base-url needs the pair in the same opts: context
credentials are never sent to a per-call URL.
Context Vars
sumsub.app.tokensumsub.secret.keysumsub.base.urlsumsub.level.name
Values
CREDENTIAL_KEYS
CREDENTIAL_KEYS: Vec [
"app-token",
"secret-key"
]
Functions
auth-headers
fn (app-token: Str, secret: Str, ts: Int, method: Str, path: Str, body: Any): Map
The three signing headers for one request: X-App-Token,
X-App-Access-Ts and X-App-Access-Sig. Exposed for testing.
Example
token ::hot::ctx/get("sumsub.app.token")
secret ::hot::ctx/get("sumsub.secret.key")
headers ::sumsub::api/auth-headers(token, secret, 1607551635, "GET", "/resources/applicants/-/levels", "")
headers.X-App-Access-Sig
build-request
fn (method: Str, path: Str, payload: Str | Bytes, content-type: Str?, extra-headers: Map, creds: Map, ts: Int): ::hot::http/HttpRequest
The signed HttpRequest for one call, given resolved credentials
({app-token, secret-key, base-url}, see resolve) and an explicit
Unix timestamp: the URL is base-url + path, payload is sent
exactly as signed, and Content-Type defaults to application/json
(Sumsub asks for it even on bodiless requests). Exposed for testing.
Example
creds ::sumsub::api/resolve()
ts ::hot::time/epoch-seconds()
req ::sumsub::api/build-request("GET", "/resources/applicants/-/levels", "", null, {}, creds, ts)
req.url
req.headers.X-App-Access-Sig
call
fn (spec: Result): Any
fn (spec: Result, opts: Map): Any
Run a request spec {method, path, body?} (as the *-request builders
return) through request. A spec that is an Err (a validation failure)
is returned as is, without a request.
Example
spec ::sumsub::applicants/request-check-request("65f0c1e2a3b4c5d6e7f80912", null)
::sumsub::api/call(spec)
// With per-call credentials
::sumsub::api/call(spec, {
app-token: ::hot::ctx/get("tenant.sumsub.token"),
secret-key: ::hot::ctx/get("tenant.sumsub.secret")
})
collect-offset
fn (fetch: Fn, offset: Int, page-size: Int, limit: Int, acc: Vec): Vec
Follow offset pages, concatenating items, until limit items or the
last page. fetch takes (offset, limit) and returns one page. Exposed
for testing; ::sumsub::applicants/list-all-notes uses it.
Example
pages (offset, size) { {items: slice([1, 2, 3], offset, min(3, add(offset, size))), totalItems: 3} }
::sumsub::api/collect-offset(pages, 0, 2, 10, []) // [1, 2, 3]
::sumsub::api/collect-offset(pages, 0, 2, 1, []) // [1]
compact
fn (value: Any): Any
Drop null-valued keys from a body, recursively through nested maps and
vectors of maps, so unset optionals are omitted rather than sent as JSON
null. Empty maps are kept (applicant: {} is meaningful). Exposed for
testing.
Example
::sumsub::api/compact({a: 1, b: null, c: {d: null}}) // {a: 1, c: {}}
encode-body
fn (body: Any): Str | Bytes
The exact payload to send and sign: a Map or Vec becomes compacted JSON,
Bytes and Str pass through, null becomes "". Exposed for testing.
Example
::sumsub::api/encode-body({a: 1, b: null}) // "{\"a\":1}"
::sumsub::api/encode-body(null) // ""
error-message
fn (status: Int, error-code: Int?, error-name: Str?, correlation-id: Str?): Str
The readable message for an error: status, errorCode/errorName and
correlationId, plus a hint for auth (401) and rate-limit (429)
failures. Never includes the description or any request data. Exposed
for testing.
Example
::sumsub::api/error-message(409, null, null, null) // "sumsub: request failed with HTTP 409"
::sumsub::api/error-message(400, 6008, "sandbox-limit", "c-1")
// "sumsub: request failed with HTTP 400 (errorCode 6008 sandbox-limit); correlationId c-1"
header
fn (headers: Any, name: Str): Str?
A header value by name, case-insensitively (inbound webhook headers are lowercase; outbound response headers may not be). Null when absent. Exposed for testing.
Example
::sumsub::api/header({"X-Image-Id": "123"}, "x-image-id") // "123"
::sumsub::api/header({}, "x-image-id") // null
int-or-null
fn (value: Any): Int?
An Int from an Int or a numeric Str, otherwise null. Never errs. Exposed for testing.
Example
::sumsub::api/int-or-null("42") // 42
::sumsub::api/int-or-null("abc") // null
is-error-code
fn (e: Any, code: Int): Bool
True when e is a Sumsub HttpError with this numeric errorCode
(e.g. 4004 for an expired signature, 6008 for the sandbox applicant
limit).
Example
response ::hot::http/HttpResponse({status: 401, headers: {}, body: {errorCode: 4004}})
e ::sumsub::api/HttpError(response)
::sumsub::api/is-error-code(e, 4004) // true
::sumsub::api/is-error-code(e, 6008) // false
next-offset
fn (page: Any, offset: Int): Int?
The offset for the page after page, fetched at offset: null when
this page was empty or totalItems says nothing is left. Exposed for
testing.
Example
::sumsub::api/next-offset({items: [1, 2], totalItems: 5}, 0) // 2
::sumsub::api/next-offset({items: [1, 2], totalItems: 2}, 0) // null
page-envelope
fn (page: Any): Map
The {items, totalItems, pageInfo?} part of a list response, which some
endpoints wrap in list. Exposed for testing.
Example
::sumsub::api/page-envelope({list: {items: [1], totalItems: 1}}) // {items: [1], totalItems: 1}
::sumsub::api/page-envelope({items: []}) // {items: []}
page-items
fn (page: Any): Vec
The items of a list response (wrapped in list or not); [] when
absent.
Example
::sumsub::api/page-items({list: {items: [1, 2]}}) // [1, 2]
::sumsub::api/page-items({}) // []
query
fn (params: Map): Str
A ?a=1&b=2 suffix from the non-null entries of params (URL-encoded);
"" when none are set.
Example
::sumsub::api/query({levelName: "basic-kyc-level", reason: null}) // "?levelName=basic-kyc-level"
::sumsub::api/query({}) // ""
request
fn (method: Str, path: Str, body: Any): Any
fn (method: Str, path: Str, body: Any, opts: Map): Any
Make a signed Sumsub request. path starts with /resources/... and
includes any query string; body is a Map or Vec (sent as JSON with
nulls dropped), Bytes, a Str, or "" for none. Returns the decoded
body on 2xx, or an Err carrying HttpError. The escape hatch for
endpoints this package does not wrap. opts overrides credentials
and settings for this call (see resolve).
Example
levels ::sumsub::api/request("GET", "/resources/applicants/-/levels", "")
resolve
fn (): Map
fn (opts: Map): Map
Resolve credentials and settings for one call: opts first, then
context, then defaults. Returns {app-token, secret-key, base-url, level-name}, or an Err naming what is missing.
opts keys: app-token and secret-key (a pair; context credentials
are then ignored for the call, and they are masked in call records),
base-url (default ::sumsub/BASE_URL; needs the pair in the same
opts) and level-name (default sumsub.level.name). A credential
present but blank or null is an Err naming the key, never a fallback
to context. Nothing is written to context, so per-call credentials
never leak across parallel flows or tenants.
Example
tenant {app-token: "sbx:...", secret-key: "..."}
::sumsub::applicants/get-applicant("65f0c1e2a3b4c5d6e7f80912", tenant)
sumsub.app.token, sumsub.secret.key, sumsub.base.url, sumsub.level.name
response-body
fn (body: Any): Any
Normalize a decoded 2xx body: empty text becomes null; anything else passes through. Exposed for testing.
Example
::sumsub::api/response-body(" ") // null
::sumsub::api/response-body({ok: true}) // {ok: true}
seg
fn (value: Any): Str
Percent-encode one path segment (an applicant id, externalUserId,
level name or transaction id).
Example
::sumsub::api/seg("user 42") // "user%2042"
send
fn (method: Str, path: Str, body: Any, content-type: Str?, extra-headers: Map): ::hot::http/HttpResponse
fn (method: Str, path: Str, body: Any, content-type: Str?, extra-headers: Map, opts: Map): ::hot::http/HttpResponse
Send a signed request and return the raw HttpResponse (or the Err
of a transport failure). A GET whose connection fails is retried
once, freshly signed; nothing else is retried. Use this when you
need response headers (e.g. X-Image-Id); request unwraps the
body. opts as for resolve.
Example
response ::sumsub::api/send("GET", "/resources/applicants/-/levels", "", null, {})
response.status
response.headers
sign
fn (secret: Str, ts: Int | Str, method: Str, path: Str, body: Any): Str
The X-App-Access-Sig value: lowercase hex HMAC-SHA256, keyed with
the App Token's secret key, over ts + METHOD + path-with-query + body. body is the exact payload sent: a Str (JSON), Bytes (a
multipart body, signed byte for byte), or ""/null for none.
Example
::sumsub::api/sign("secret", 1607551635, "GET", "/resources/applicants/123?fields=info", "")
string-to-sign
fn (ts: Int | Str, method: Str, path: Str): Str
The text prefix Sumsub signs before the body: ts + METHOD + path,
where path starts with / and includes the query string exactly as
sent. Exposed for testing.
Example
::sumsub::api/string-to-sign(1607551635, "get", "/resources/applicants/123/one")
// "1607551635GET/resources/applicants/123/one"
unwrap
fn (response: Result): Any
The decoded body of a 2xx response (null when empty), the Err of a
failed transport, or err(HttpError) for a non-2xx response.
Example
::sumsub::api/unwrap(::hot::http/HttpResponse({status: 200, headers: {}, body: {ok: true}})) // {ok: true}
::sumsub::api/unwrap(::hot::http/HttpResponse({status: 200, headers: {}, body: ""})) // null
is-err(::sumsub::api/unwrap(::hot::http/HttpResponse({status: 404, headers: {}, body: {}}))) // true
Types
HttpError
HttpError type {
status: Int,
headers: Map,
body: Any,
message: Str,
description: Str?,
error-code: Int?,
error-name: Str?,
correlation-id: Str?,
retry-after: Int?
}
A non-2xx Sumsub response. status, headers and body as in the
sibling packages, plus Sumsub's error object lifted to the top:
error-code (e.g. 4003 signature mismatch, 4004 request expired,
6008 sandbox applicant limit), error-name, correlation-id (quote
it to Sumsub support), description (Sumsub's text; it can echo
values you sent, so don't log it where PII must not go) and
retry-after (seconds, from Retry-After, set on the temporary 409
from approve/reject). message is a readable summary that never
contains request data or the description.