Users
Initiate Tier Escalation
Starts a tier upgrade (escalation) for one of your users. Kravata looks at the user’s current tier in the currency and returns the action the user has to complete to move to the next tier, for example uploading documents.
If the user already has a pending escalation for the same action, the same request is returned; calling it again does not create another one. The user completes the action in the Kravata widget; when it is approved, the new tier shows up in GET /api/v1/tier/user-assignments.
Request
| Field | Type | Required | Description |
|---|---|---|---|
| Authorization | Header | Yes | Bearer <access_token> obtained from POST /api/v1/client/token. |
| user_id | Path | Yes | Identifier of the user. |
| currency | Body | No | USD or COP. Default USD. The body can be omitted. |
Response
| Field | Description |
|---|---|
| requestId | Identifier of the escalation request. |
| actionType | What the user has to do: FORM_URL, QR_APP, VIDEO_KYC, DOC_UPLOAD or NOTIFY_ONLY. |
| actionPayload | Data for the action (for example a URL or a form identifier), or null. |
| message | Message for the user, with the limits of their current tier. |
| expiresAt | When the request expires (UTC). After that, call this endpoint again. |
| fromTierId | Current tier of the user. |
| toTierId | Tier the user moves to when the action is approved. |
Errors
| Status | When |
|---|---|
| 404 | The user does not exist, has no tier in that currency, or their tier has no upgrade configured. |
| 422 | user_id is not a valid UUID. |
POST
/
api
/
v1
/
admin
/
tier
/
escalation-requests
/
{user_id}
Initiate Tier Escalation
curl --request POST \
--url https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"currency": "USD"
}
'import requests
url = "https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}"
payload = { "currency": "USD" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({currency: 'USD'})
};
fetch('https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}', 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://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}",
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([
'currency' => 'USD'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}"
payload := strings.NewReader("{\n \"currency\": \"USD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"USD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"USD\"\n}"
response = http.request(request)
puts response.read_body{
"requestId": "c8967e40-8afb-4c3f-8d1c-153261768104",
"actionType": "DOC_UPLOAD",
"actionPayload": "<action payload>",
"message": "Your current tier lets you deposit up to 1,000 USD per transaction and 4,000 USD per month. To increase it, upload your documents.",
"expiresAt": "2026-10-24T20:16:44",
"fromTierId": "d2871503-1fb1-47ce-8a3f-3522b2e246c0",
"toTierId": "28d532c0-cab2-4dfd-bd1e-1c82a942a050"
}Initiate Tier Escalation
curl --request POST \
--url https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"currency": "USD"
}
'import requests
url = "https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}"
payload = { "currency": "USD" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({currency: 'USD'})
};
fetch('https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}', 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://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}",
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([
'currency' => 'USD'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}"
payload := strings.NewReader("{\n \"currency\": \"USD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"USD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://test-api-kore.kravata.co/api/v1/admin/tier/escalation-requests/{user_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"USD\"\n}"
response = http.request(request)
puts response.read_body{
"requestId": "c8967e40-8afb-4c3f-8d1c-153261768104",
"actionType": "DOC_UPLOAD",
"actionPayload": "<action payload>",
"message": "Your current tier lets you deposit up to 1,000 USD per transaction and 4,000 USD per month. To increase it, upload your documents.",
"expiresAt": "2026-10-24T20:16:44",
"fromTierId": "d2871503-1fb1-47ce-8a3f-3522b2e246c0",
"toTierId": "28d532c0-cab2-4dfd-bd1e-1c82a942a050"
}