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

Optional
  • sumsub.app.token
  • sumsub.secret.key
  • sumsub.base.url
  • sumsub.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"
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)
Context Vars: 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.