API reference
KYC
Generated HTTP reference for the 1 operation the published OpenAPI document describes under kyc.
3 min read
KYC
This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.
Base URL: https://api.codespar.dev
Every operation below requires a Bearer token. See Authentication.
GET /v1/kyc/onboard/{proposalId}/status
Poll a KYC account application
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
proposalId | string | yes | The application id the create call returned. It addresses a recorded proposal, and an id with no recorded proposal is refused rather than looked up. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
consumer_id | string | no | The consumer to bind a provisioned account to, when the recorded proposal does not already name one. Precedence runs the other way from what the parameter suggests: the recorded proposal's consumer WINS, and this value is the fallback used only when the proposal recorded none. Omitting it falls back to the id in the path. |
document_number | string | yes | REQUIRED, and its absence is a 400 rather than a default. It is a CLAIM about what the application is for, checked against the document the recorded proposal actually verified, and it never addresses the provider: the account is always fetched for the proposal's own document. A claim that does not match the recorded one is refused before any provider call and nothing is written. |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
400 | object | Bad Request — document_number was absent. A bare body with one key, not the \{ error: \{ code, message \} \} envelope the newer routes use. |
403 | object | Forbidden — the provisioning write named a resource outside the organization and project these credentials authenticate for. The body is the tenant control's own two keys and carries nothing from the database's message. |
502 | object | Bad Gateway — the provider lookup or the provisioning that follows it failed. Also the status for a refused ownership proof (no recorded proposal, or a document_number that does not match the one the proposal verified): message distinguishes them, the code does not. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
account | string,null | yes | The provisioned account number, once one exists. |
funding_source_id | string,null | yes | The consumer's funding source, written when the application is approved. Provisioning is idempotent on a key derived from the consumer, so polling this endpoint repeatedly after approval returns the same id and creates nothing new. |
hosted_url | string,null | yes | The document-check webview link while it is outstanding; null otherwise. |
pix_key | string,null | yes | The Pix key registered for the account, either just now or previously — registration returns early when the key already exists, so a repeated poll does not re-register. |
pix_key_registration_error | string | no | Present ONLY when the account was provisioned but its Pix-key registration failed. It is deliberately not an error status: the account is real and usable, and the key is retried lazily the next time the consumer needs to receive. Absent means either the key registered or there is no account yet — read pix_key to tell those apart. |
pix_key_type | string,null | yes | — |
status | "pending" | "documentscopy_pending" | "approved" | "rejected" | yes | Four values, and the fourth is not the type's fifth. The resolver that serves this route is the only producer, and enumerating every one of its returns gives exactly these four; unknown exists in the shared union and is returned by nothing on this path. documentscopy_pending means the holder still has to finish the document check, and hosted_url is where they finish it. pending is the widest of the four: it covers the provider's own PENDING and PROCESSING, the case where it reported no status at all, and a proposal that is past those states but whose account could not yet be read back. Poll again for all three. |
Example response
{
"status": "pending",
"pix_key_registration_error": "string"
}Example request
curl -X GET https://api.codespar.dev/v1/kyc/onboard/{proposalId}/status \
-H "Authorization: Bearer $CODESPAR_API_KEY"