Skip to main content

​
Overview

The exposes two read-only endpoints for third-party consumers to access a user’s verification data:
  • KYC Details — verification status, personal information, document metadata, and rejection details
  • Document Images — binary image data for each submitted identity document
Both endpoints require dual authentication: an API key with get_kyc scope and a PINT token with sr:us:pint:identity:kyc_read scope.

​
Prerequisites

  • SIS API key with get_kyc scope
  • User’s external_id (from SRI lookup or user creation)
  • PINT token with sr:us:pint:identity:kyc_read scope (obtained via Token Exchange)

​
Authentication

Every request to the KYC endpoints must include both authentication credentials:
HeaderValuePurpose
AuthorizationBearer <api-key>API key with get_kyc scope
x-sumvin-pint-token<jwt>PINT token with sr:us:pint:identity:kyc_read scope

​
Step 1: Obtain a PINT Token

Exchange a signed PINT for a JWT, requesting the sr:us:pint:identity:kyc_read scope: 
curl -X POST https://sis.sumvin.com/v0/sis/token/pint \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "pint": {
      "wallet": "0xE23c9A70BC749EBddd8c78a864fd911D04E9e992",
      "nonce": 42,
      "statement": "KYC data access for partner X",
      "scopes": ["sr:us:pint:identity:kyc_read"],
      "resources": [],
      "maxAmount": 0,
      "maxAmountToken": "0x0000000000000000000000000000000000000000",
      "expiresAt": 1740000000
    },
    "signature": "0x...",
    "audience": "partner-x.example.com"
  }'
The response includes a token field containing the PINT JWT. Use this as the x-sumvin-pint-token header value in subsequent requests.

​
Step 2: Look Up the User

Use the SRI lookup endpoint to resolve a user and obtain their external_id: 
curl https://sis.sumvin.com/v0/users/{sri} \
  -H "Authorization: Bearer <your-api-key>"
The external_id from the response is used as {user_id} in the KYC endpoints below.

​
Step 3: Get KYC Details

Fetch the user’s verification status, personal information, and document metadata: 
curl https://sis.sumvin.com/v0/users/user-abc123/kyc \
  -H "Authorization: Bearer <your-api-key>" \
  -H "x-sumvin-pint-token: <pint-jwt>"

​
Response — 200 OK

{
  "status": "approved",
  "verified_at": 1704067200000,
  "rejected_at": null,
  "started_at": 1704060000000,
  "personal_info": {
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1990-05-15",
    "nationality": "GBR",
    "country_of_residence": "GBR"
  },
  "documents": [
    {
      "document_type": "PASSPORT",
      "country": "GBR",
      "status": "approved",
      "submitted_at": null,
      "image_ids": ["img-abc123", "img-def456"]
    }
  ],
  "verification_complete": true,
  "verification_passed": true,
  "rejection": null,
  "_links": {
    "self": { "href": "/v0/users/user-abc123/kyc" }
  }
}

​
Response Fields

FieldTypeDescription
statusstringCurrent KYC status: pending, in_progress, approved, retry, or rejected
verified_atinteger or nullApproval timestamp (epoch milliseconds)
rejected_atinteger or nullRejection timestamp (epoch milliseconds)
started_atinteger or nullWhen verification was initiated (epoch milliseconds)
personal_infoobject or nullIdentity information extracted from documents
documentsarraySubmitted documents with metadata and image references
verification_completebooleanWhether all required documents have been submitted
verification_passedbooleanWhether verification passed all checks
rejectionobject or nullRejection details, if applicable

​
Personal Info

FieldTypeDescription
first_namestringFirst name from identity document
last_namestringLast name from identity document
date_of_birthstringDate of birth (YYYY-MM-DD)
nationalitystringNationality (ISO 3166-1 alpha-3)
country_of_residencestringCountry of residence (ISO 3166-1 alpha-3)

​
Documents

FieldTypeDescription
document_typestringType of document: PASSPORT, ID_CARD, DRIVERS, RESIDENCE_PERMIT
countrystringIssuing country (ISO 3166-1 alpha-3)
statusstringDocument verification status
submitted_atinteger or nullSubmission timestamp (epoch milliseconds)
image_idsarray of stringsImage identifiers for fetching document images

​
Rejection

FieldTypeDescription
can_retrybooleantrue if the user can resubmit, false for terminal rejections
messagestringHuman-readable rejection reason

​
Step 4: Fetch Document Images

Document images are fetched individually using the image_ids from the KYC details response. 
curl https://sis.sumvin.com/v0/users/user-abc123/kyc/document/img-abc123 \
  -H "Authorization: Bearer <your-api-key>" \
  -H "x-sumvin-pint-token: <pint-jwt>" \
  --output document.jpg
The response is binary image data (image/jpeg, image/png, etc.), not JSON. Set your HTTP client to handle binary responses.
  • Response includes Cache-Control: private, max-age=300
  • Images are streamed directly from the upstream provider
  • Content type is set in the Content-Type response header

​
Complete Example

import httpx

BASE = "https://sis.sumvin.com"
HEADERS = {
    "Authorization": "Bearer <your-api-key>",
    "x-sumvin-pint-token": "<pint-jwt>",
}

# 1. Get KYC details
kyc = httpx.get(f"{BASE}/v0/users/{user_id}/kyc", headers=HEADERS).json()

# 2. Check status
if kyc["status"] != "approved":
    print(f"KYC not approved: {kyc['status']}")

# 3. Download document images
for doc in kyc["documents"]:
    for image_id in doc["image_ids"]:
        resp = httpx.get(
            f"{BASE}/v0/users/{user_id}/kyc/document/{image_id}",
            headers=HEADERS,
        )
        with open(f"{image_id}.jpg", "wb") as f:
            f.write(resp.content)

​
Error Handling

All errors follow RFC 7807 Problem Details:
StatusCodeMeaningAction
401PINT-401-003Missing x-sumvin-pint-token headerInclude a valid PINT token
401PINT-401-004Invalid or malformed PINT tokenCheck token format and expiry
403PINT-403-003PINT token missing sr:us:pint:identity:kyc_read scopeRequest token with correct scope
403SIS-403-001API key missing get_kyc scopeContact account manager for scope upgrade
404SRI-404-001User not foundVerify user_id is correct
404KYC-404-001No KYC record for userUser has not started verification
502KYC-502-001Upstream provider unavailableRetry after short delay

​
Next Steps

ConcernWhere to goWhen
Scope catalogScopes referenceWhen scoping what a PINT may do
SIS authSIS authenticationWhen provisioning API keys
Token exchangeToken exchangeWhen minting the PINT JWTs this endpoint consumes