Create Sumsub hosted KYC session

curl --request POST \
  --url https://api.pods.finance/api/v1/kyc/hosted/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "cpf": "52998224725",
  "email": "[email protected]",
  "walletAddress": "EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj",
  "externalUserId": "app-user-001",
  "redirectUrl": "https://app.example.com/kyc/return"
}
'

import requests

url = "https://api.pods.finance/api/v1/kyc/hosted/sessions"

payload = {
    "cpf": "52998224725",
    "email": "[email protected]",
    "walletAddress": "EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj",
    "externalUserId": "app-user-001",
    "redirectUrl": "https://app.example.com/kyc/return"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cpf: '52998224725',
    email: '[email protected]',
    walletAddress: 'EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj',
    externalUserId: 'app-user-001',
    redirectUrl: 'https://app.example.com/kyc/return'
  })
};

fetch('https://api.pods.finance/api/v1/kyc/hosted/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pods.finance/api/v1/kyc/hosted/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cpf' => '52998224725',
    'email' => '[email protected]',
    'walletAddress' => 'EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj',
    'externalUserId' => 'app-user-001',
    'redirectUrl' => 'https://app.example.com/kyc/return'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pods.finance/api/v1/kyc/hosted/sessions"

	payload := strings.NewReader("{\n  \"cpf\": \"52998224725\",\n  \"email\": \"[email protected]\",\n  \"walletAddress\": \"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj\",\n  \"externalUserId\": \"app-user-001\",\n  \"redirectUrl\": \"https://app.example.com/kyc/return\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pods.finance/api/v1/kyc/hosted/sessions")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cpf\": \"52998224725\",\n  \"email\": \"[email protected]\",\n  \"walletAddress\": \"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj\",\n  \"externalUserId\": \"app-user-001\",\n  \"redirectUrl\": \"https://app.example.com/kyc/return\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pods.finance/api/v1/kyc/hosted/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cpf\": \"52998224725\",\n  \"email\": \"[email protected]\",\n  \"walletAddress\": \"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj\",\n  \"externalUserId\": \"app-user-001\",\n  \"redirectUrl\": \"https://app.example.com/kyc/return\"\n}"

response = http.request(request)
puts response.read_body

{
  "kycUserId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "requiresWebView": true,
  "verificationLink": "https://in.sumsub.com/websdk/p/sbx_example",
  "verificationLinkExpiresAt": "2026-10-19T18:30:00.000Z",
  "reason": {
    "code": "TAX_ID_ALREADY_VERIFIED",
    "message": "This person is already verified under another record.",
    "retryable": false,
    "retryFrom": "liveness"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

Ramp

Create Sumsub hosted KYC session

Starts, reopens or answers a KYC verification on a Sumsub-hosted page. Pods creates the applicant and returns a link; the applicant completes document, selfie and personal data in the browser and is redirected back to your app. Poll GET /api/v1/kyc/status for the result: the redirect is a hint and not the source of truth. Idempotent by CPF: the same CPF returns the same kycUserId, and the same link while it has more than five minutes left. An identity already approved on Avenia is answered as approved without a link. Available only to customers enabled for the hosted flow.

POST

api

kyc

hosted

sessions

Create Sumsub hosted KYC session

curl --request POST \
  --url https://api.pods.finance/api/v1/kyc/hosted/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "cpf": "52998224725",
  "email": "[email protected]",
  "walletAddress": "EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj",
  "externalUserId": "app-user-001",
  "redirectUrl": "https://app.example.com/kyc/return"
}
'

import requests

url = "https://api.pods.finance/api/v1/kyc/hosted/sessions"

payload = {
    "cpf": "52998224725",
    "email": "[email protected]",
    "walletAddress": "EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj",
    "externalUserId": "app-user-001",
    "redirectUrl": "https://app.example.com/kyc/return"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cpf: '52998224725',
    email: '[email protected]',
    walletAddress: 'EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj',
    externalUserId: 'app-user-001',
    redirectUrl: 'https://app.example.com/kyc/return'
  })
};

fetch('https://api.pods.finance/api/v1/kyc/hosted/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pods.finance/api/v1/kyc/hosted/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cpf' => '52998224725',
    'email' => '[email protected]',
    'walletAddress' => 'EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj',
    'externalUserId' => 'app-user-001',
    'redirectUrl' => 'https://app.example.com/kyc/return'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pods.finance/api/v1/kyc/hosted/sessions"

	payload := strings.NewReader("{\n  \"cpf\": \"52998224725\",\n  \"email\": \"[email protected]\",\n  \"walletAddress\": \"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj\",\n  \"externalUserId\": \"app-user-001\",\n  \"redirectUrl\": \"https://app.example.com/kyc/return\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pods.finance/api/v1/kyc/hosted/sessions")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cpf\": \"52998224725\",\n  \"email\": \"[email protected]\",\n  \"walletAddress\": \"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj\",\n  \"externalUserId\": \"app-user-001\",\n  \"redirectUrl\": \"https://app.example.com/kyc/return\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pods.finance/api/v1/kyc/hosted/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cpf\": \"52998224725\",\n  \"email\": \"[email protected]\",\n  \"walletAddress\": \"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj\",\n  \"externalUserId\": \"app-user-001\",\n  \"redirectUrl\": \"https://app.example.com/kyc/return\"\n}"

response = http.request(request)
puts response.read_body

{
  "kycUserId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "requiresWebView": true,
  "verificationLink": "https://in.sumsub.com/websdk/p/sbx_example",
  "verificationLinkExpiresAt": "2026-10-19T18:30:00.000Z",
  "reason": {
    "code": "TAX_ID_ALREADY_VERIFIED",
    "message": "This person is already verified under another record.",
    "retryable": false,
    "retryFrom": "liveness"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

Authorizations

x-api-key

string

header

required

API key for authentication. Obtain from your Pods dashboard.

Body

application/json

Sumsub hosted KYC session payload

cpf

string

required

Brazilian CPF. Pods normalizes and hashes this value. It is sent to Sumsub as the applicant tax id and is never returned.

Example:

"52998224725"

string<email>

required

Applicant email

Example:

"[email protected]"

walletAddress

string

required

Applicant wallet. Checksummed EVM address or Solana public key.

Example:

"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj"

externalUserId

string

Optional id from your system for support correlation. Stored on the profile; it is not used to look anything up.

Example:

"app-user-001"

redirectUrl

string

Where the applicant is sent back to after a successful verification. It must be https, carry no credentials and match, by origin and path, an entry of the redirect allowlist configured for your account. The query string is kept; the fragment is dropped. When omitted, the first allowlisted URL is used.

Maximum string length: 1024

Example:

"https://app.example.com/kyc/return"

Response

Session created, reopened, or already resolved (approved, under analysis, rejected)

Sumsub hosted KYC session. Calling the endpoint again with the same CPF returns the same session, with the same link while it still has more than five minutes left, and a new link after that.

kycUserId

string<uuid>

required

Pods-generated public KYC user id. Stays the same for the same CPF on your account.

Example:

"550e8400-e29b-41d4-a716-446655440000"

status

enum<string>

required

Normalized Pods KYC status

Available options:

created,

provider_pending,

approved,

rejected,

rejected_retryable,

blocked

Example:

"created"

requiresWebView

boolean

required

True when verificationLink is present and the applicant must open it.

Example:

true

verificationLink

string<uri> | null

required

Sumsub hosted verification page. Open it in the applicant's browser. A bearer link: do not log it or share it. Null when there is nothing to open: the profile is already approved, under analysis, rejected or blocked.

Example:

"https://in.sumsub.com/websdk/p/sbx_example"

verificationLinkExpiresAt

string<date-time> | null

required

When the link stops opening. It does not end the verification: call this endpoint again for a new link, and poll GET /api/v1/kyc/status for the result.

Example:

"2026-10-19T18:30:00.000Z"

reason

object

Present only when status is rejected or rejected_retryable.

Show child attributes

Overview

Health

Swap

Tracking

Strategies

Ondo

Tokens

Transfer

Wallets

Smart Account

Ramp

Create Sumsub hosted KYC session

Authorizations

Body

Response