Add an item to the information request

curl --request POST \
  --url https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items \
  --header 'Content-Type: application/json' \
  --cookie ds-prod-session= \
  --data '
{
  "field_key": "registration_number",
  "message": "The number does not match the registry, please re-enter it.",
  "section_key": "registration",
  "audience": "merchant",
  "target_kind": "field"
}
'

import requests

url = "https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items"

payload = {
    "field_key": "registration_number",
    "message": "The number does not match the registry, please re-enter it.",
    "section_key": "registration",
    "audience": "merchant",
    "target_kind": "field"
}
headers = {
    "cookie": "ds-prod-session=",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {cookie: 'ds-prod-session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    field_key: 'registration_number',
    message: 'The number does not match the registry, please re-enter it.',
    section_key: 'registration',
    audience: 'merchant',
    target_kind: 'field'
  })
};

fetch('https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items', 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.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items",
  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([
    'field_key' => 'registration_number',
    'message' => 'The number does not match the registry, please re-enter it.',
    'section_key' => 'registration',
    'audience' => 'merchant',
    'target_kind' => 'field'
  ]),
  CURLOPT_COOKIE => "ds-prod-session=",
  CURLOPT_HTTPHEADER => [
    "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://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items"

	payload := strings.NewReader("{\n  \"field_key\": \"registration_number\",\n  \"message\": \"The number does not match the registry, please re-enter it.\",\n  \"section_key\": \"registration\",\n  \"audience\": \"merchant\",\n  \"target_kind\": \"field\"\n}")

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

	req.Header.Add("cookie", "ds-prod-session=")
	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.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items")
  .header("cookie", "ds-prod-session=")
  .header("Content-Type", "application/json")
  .body("{\n  \"field_key\": \"registration_number\",\n  \"message\": \"The number does not match the registry, please re-enter it.\",\n  \"section_key\": \"registration\",\n  \"audience\": \"merchant\",\n  \"target_kind\": \"field\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items")

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

request = Net::HTTP::Post.new(url)
request["cookie"] = 'ds-prod-session='
request["Content-Type"] = 'application/json'
request.body = "{\n  \"field_key\": \"registration_number\",\n  \"message\": \"The number does not match the registry, please re-enter it.\",\n  \"section_key\": \"registration\",\n  \"audience\": \"merchant\",\n  \"target_kind\": \"field\"\n}"

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

{
  "code": "invalid_target",
  "message": "Unknown remediation target",
  "param": "registration.not_a_field"
}

{
  "code": "case_not_found",
  "message": "Case not found"
}

{
  "code": "case_not_reviewable",
  "message": "Case is not open to remediation"
}

{
  "errors": [
    {
      "field": "<string>",
      "message": "<string>",
      "type": "<string>"
    }
  ],
  "message": "<string>"
}

{
  "case_id": "019f179b-0fa7-72c8-818e-819652540477",
  "case_status": "in_remediation",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "019f179b-0fa7-72c8-818e-819652540477",
  "items": [
    {
      "audience": "merchant",
      "canceled_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "019f1383-8f38-7d31-b921-39310a19b444",
      "field_key": "registration_number",
      "id": "019f179b-0fa7-72c8-818e-819652540477",
      "last_value": null,
      "message": "The number does not match the registry, please re-enter it.",
      "new_value": null,
      "request_id": "019f179b-0fa7-72c8-818e-819652540477",
      "resolved_at": "2023-11-07T05:31:56Z",
      "section_key": "registration",
      "status": "open",
      "target_kind": "field"
    }
  ],
  "received_at": "2023-11-07T05:31:56Z",
  "sent_at": "2023-11-07T05:31:56Z",
  "status": "draft",
  "widget_url": "https://kyb.dataspike.io/KYB0123456789abcdef"
}

KYB Remediation

Add an item to the information request

Adds one thing to fix, creating the draft round if the case has none. The target is an existing catalog entry addressed by section_key + field_key — officers cannot invent a field or a slot, and there is no item title: the label comes from the catalog and the officer’s text goes in message. An unknown target is a 400 invalid_target.

target_kind is field (a field of a fields-kind section) or document (a document GROUP of the documents section, its group key carried in field_key, e.g. {"target_kind":"document","section_key":"documents","field_key":"bank"}). The kind must match the section: a field section holds no groups and the documents section holds no fields. owner is a later phase, which is also why the per-owner government-ID group of the parties section cannot be targeted. audience defaults to merchant.

Nothing reaches the applicant until the round is sent. The one exception is adding to a round that is already with them (the case is in_remediation): that item is sent immediately, because an unsent item would leave its field locked while still counting as unanswered.

One open ask per target: a second item for a field the round already covers is a 409 target_already_requested, carrying that section.field as param. Edit the existing item’s message instead, or withdraw it first. A withdrawn item does not block a re-ask.

POST

webapi

kyb

organization

{organizationId}

verifications

{caseId}

info-request

items

Add an item to the information request

curl --request POST \
  --url https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items \
  --header 'Content-Type: application/json' \
  --cookie ds-prod-session= \
  --data '
{
  "field_key": "registration_number",
  "message": "The number does not match the registry, please re-enter it.",
  "section_key": "registration",
  "audience": "merchant",
  "target_kind": "field"
}
'

import requests

url = "https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items"

payload = {
    "field_key": "registration_number",
    "message": "The number does not match the registry, please re-enter it.",
    "section_key": "registration",
    "audience": "merchant",
    "target_kind": "field"
}
headers = {
    "cookie": "ds-prod-session=",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {cookie: 'ds-prod-session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    field_key: 'registration_number',
    message: 'The number does not match the registry, please re-enter it.',
    section_key: 'registration',
    audience: 'merchant',
    target_kind: 'field'
  })
};

fetch('https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items', 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.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items",
  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([
    'field_key' => 'registration_number',
    'message' => 'The number does not match the registry, please re-enter it.',
    'section_key' => 'registration',
    'audience' => 'merchant',
    'target_kind' => 'field'
  ]),
  CURLOPT_COOKIE => "ds-prod-session=",
  CURLOPT_HTTPHEADER => [
    "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://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items"

	payload := strings.NewReader("{\n  \"field_key\": \"registration_number\",\n  \"message\": \"The number does not match the registry, please re-enter it.\",\n  \"section_key\": \"registration\",\n  \"audience\": \"merchant\",\n  \"target_kind\": \"field\"\n}")

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

	req.Header.Add("cookie", "ds-prod-session=")
	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.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items")
  .header("cookie", "ds-prod-session=")
  .header("Content-Type", "application/json")
  .body("{\n  \"field_key\": \"registration_number\",\n  \"message\": \"The number does not match the registry, please re-enter it.\",\n  \"section_key\": \"registration\",\n  \"audience\": \"merchant\",\n  \"target_kind\": \"field\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/webapi/v4/kyb/organization/{organizationId}/verifications/{caseId}/info-request/items")

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

request = Net::HTTP::Post.new(url)
request["cookie"] = 'ds-prod-session='
request["Content-Type"] = 'application/json'
request.body = "{\n  \"field_key\": \"registration_number\",\n  \"message\": \"The number does not match the registry, please re-enter it.\",\n  \"section_key\": \"registration\",\n  \"audience\": \"merchant\",\n  \"target_kind\": \"field\"\n}"

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

{
  "code": "invalid_target",
  "message": "Unknown remediation target",
  "param": "registration.not_a_field"
}

{
  "code": "case_not_found",
  "message": "Case not found"
}

{
  "code": "case_not_reviewable",
  "message": "Case is not open to remediation"
}

{
  "errors": [
    {
      "field": "<string>",
      "message": "<string>",
      "type": "<string>"
    }
  ],
  "message": "<string>"
}

{
  "case_id": "019f179b-0fa7-72c8-818e-819652540477",
  "case_status": "in_remediation",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "019f179b-0fa7-72c8-818e-819652540477",
  "items": [
    {
      "audience": "merchant",
      "canceled_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "019f1383-8f38-7d31-b921-39310a19b444",
      "field_key": "registration_number",
      "id": "019f179b-0fa7-72c8-818e-819652540477",
      "last_value": null,
      "message": "The number does not match the registry, please re-enter it.",
      "new_value": null,
      "request_id": "019f179b-0fa7-72c8-818e-819652540477",
      "resolved_at": "2023-11-07T05:31:56Z",
      "section_key": "registration",
      "status": "open",
      "target_kind": "field"
    }
  ],
  "received_at": "2023-11-07T05:31:56Z",
  "sent_at": "2023-11-07T05:31:56Z",
  "status": "draft",
  "widget_url": "https://kyb.dataspike.io/KYB0123456789abcdef"
}

Authorizations

ds-prod-session

string

required

Session cookie for web dashboard authentication.

Path Parameters

organizationId

string

required

Organization id.

caseId

string

required

KYB case id (the id from the list).

Body

Request body for kyb.AddInfoRequestItemRequest

AddInfoRequestItemRequest schema

field_key

string

required

Example:

"registration_number"

message

string

required

Maximum string length: 2000

Example:

"The number does not match the registry, please re-enter it."

section_key

string

required

Example:

"registration"

audience

enum<string> | null

Available options:

merchant

Example:

"merchant"

target_kind

enum<string> | null

Available options:

field,

document

Example:

"field"

Response

Created

API documentation

KYB

KYT

Add an item to the information request

Authorizations

Path Parameters

Body

Response