API Overview

# Exchange client credentials for a bearer token (~10 min TTL)
TOKEN=$(curl -fsS -X POST "$BASE_URL/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=PublicApi" | jq -r '.access_token')

# Send it on every request:
#   -H "Authorization: Bearer $TOKEN"

import requests

BASE_URL = "https://api.knowyourcustomer.dev"   # free Sandbox

resp = requests.post(
    f"{BASE_URL}/connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": "PublicApi",
    },
    timeout=30,
)
resp.raise_for_status()
token = resp.json()["access_token"]   # ~10 min TTL
headers = {"Authorization": f"Bearer {token}"}

const BASE_URL = "https://api.knowyourcustomer.dev"; // free Sandbox

const body = new URLSearchParams({
  grant_type: "client_credentials",
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  scope: "PublicApi",
});
const res = await fetch(`${BASE_URL}/connect/token`, { method: "POST", body });
if (!res.ok) throw new Error(`token failed: ${res.status}`);
const { access_token } = await res.json();   // ~10 min TTL
const headers = { Authorization: `Bearer ${access_token}` };

#!/usr/bin/env bash
#
# KYC Public API v2: full onboarding journey (curl + bash)
#
# Journey: token -> search -> create -> poll to Ready -> members + org-chart
#          -> get an individual member -> upload document (good vs forged)
#          -> AML view -> close (Approved) -> download report PDF
#
# Requires: bash, curl, jq
# Usage:    CLIENT_ID=... CLIENT_SECRET=... ./journey.sh
#
set -euo pipefail

BASE_URL="${BASE_URL:-https://api.knowyourcustomer.dev}"   # free Sandbox
CLIENT_ID="${CLIENT_ID:-YOUR_CLIENT_ID}"
CLIENT_SECRET="${CLIENT_SECRET:-YOUR_CLIENT_SECRET}"

# What we want to onboard
ISO="GB"
QUERY="CROPWELL BISHOP"

# --- 1. Get an access token -------------------------------------------------
echo "==> Requesting access token"
TOKEN=$(curl -fsS -X POST "$BASE_URL/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=PublicApi" | jq -r '.access_token')

auth=(-H "Authorization: Bearer $TOKEN")

# --- 2. Search the registry -------------------------------------------------
echo "==> Searching registry for '$QUERY' in $ISO"
RAWNAME=$(curl -fsS -X POST "$BASE_URL/v2/Companies/search" "${auth[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"codeiso31662\":\"$ISO\",\"query\":\"$QUERY\"}" \
  | jq -r '.companySearch.searchResults[0].rawname')
echo "    matched: $RAWNAME"

# --- 3. Create the company case ---------------------------------------------
echo "==> Creating company case"
CASE_ID=$(curl -fsS -X POST "$BASE_URL/v2/Companies" "${auth[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"rawname\":\"$RAWNAME\",\"codeiso31662\":\"$ISO\"}" \
  | jq -r '.caseDetail.details.common.caseCommonId')
echo "    caseCommonId: $CASE_ID"

# --- 4. Poll until Ready (statusId == 3) ------------------------------------
echo "==> Polling for Ready"
for i in $(seq 1 60); do
  STATUS=$(curl -fsS "$BASE_URL/v2/Companies/$CASE_ID" "${auth[@]}" \
    | jq -r '.caseDetail.details.common.statusId')
  echo "    statusId=$STATUS"
  if [ "$STATUS" = "3" ]; then break; fi
  if [ "$STATUS" = "8" ]; then echo "    case expired/failed"; exit 1; fi
  sleep 5
done

# --- 5. Members + org-chart -------------------------------------------------
echo "==> Fetching members"
MEMBERS=$(curl -fsS "$BASE_URL/v2/Companies/$CASE_ID/members" "${auth[@]}")
echo "$MEMBERS" | jq '{controlling: (.controllingEntitiesAndIndividuals | length),
                        shareholders: (.shareholdersAndBeneficialOwners | length)}'

echo "==> Fetching org-chart (recursive ownership tree)"
curl -fsS "$BASE_URL/v2/Companies/$CASE_ID/org-chart" "${auth[@]}" \
  | jq '{root: .name, shareholders: [.shareholders[]?.name]}'

# Pick the first individual controlling party (memberType == "Individual")
INDIV_ID=$(echo "$MEMBERS" \
  | jq -r 'first(.controllingEntitiesAndIndividuals[] | select(.memberType=="Individual") | .member.caseCommonId)')
echo "    individual member caseCommonId: $INDIV_ID"

# --- 6. Get the individual + its mandatory docs -----------------------------
echo "==> Fetching individual member $INDIV_ID"
curl -fsS "$BASE_URL/v2/Individuals/$INDIV_ID" "${auth[@]}" \
  | jq '.caseDetail.details.common | {caseCommonId, statusId, statusName}'

echo "==> Mandatory documents for the individual"
curl -fsS "$BASE_URL/v2/Individuals/$INDIV_ID/documents/mandatory" "${auth[@]}" | jq .
# typically: ["photoid","selfie","poa"]

# --- 7. Upload a document (multipart): good then forged ---------------------
# Replace ./passport.jpg / ./forged.jpg with real files when running.
echo "==> Uploading a (good) identity document"
curl -fsS -X POST "$BASE_URL/v2/Individuals/$INDIV_ID/documents/upload" "${auth[@]}" \
  -F "file=@./passport.jpg" \
  -F "name=Passport" \
  -F "fileCat=photoid" \
  -F "caseCommonId=$INDIV_ID" \
  -F "isCompany=false" \
  | jq '{caseDocumentId, category, prevalidationMessages}'
# Good document -> prevalidationMessages: []

echo "==> Uploading a (forged) identity document, expect a prevalidation message"
curl -fsS -X POST "$BASE_URL/v2/Individuals/$INDIV_ID/documents/upload" "${auth[@]}" \
  -F "file=@./forged.jpg" \
  -F "name=Passport (forged)" \
  -F "fileCat=photoid" \
  -F "caseCommonId=$INDIV_ID" \
  -F "isCompany=false" \
  | jq '.prevalidationMessages'
# Forged document -> [{ "key": "IdentityDocumentNotRecognized", ... }]

# --- 8. AML view ------------------------------------------------------------
echo "==> AML checks for the company"
curl -fsS "$BASE_URL/v2/Companies/$CASE_ID/amlchecks" "${auth[@]}" \
  | jq '{worldChecks: (.worldChecks | length), lexisNexisChecks: (.lexisNexisChecks | length)}'

# --- 9. Close the case with a decision --------------------------------------
echo "==> Recording decision: Approved"
curl -fsS -X PATCH "$BASE_URL/v2/Companies/$CASE_ID/status" "${auth[@]}" \
  -H "Content-Type: application/json" \
  -d '{"status":"Approved"}' | jq .

# --- 10. Download the KYC report PDF ----------------------------------------
echo "==> Downloading KYC report PDF"
curl -fsS "$BASE_URL/v2/Companies/$CASE_ID/report?language=en" "${auth[@]}" \
  -o "kyc-report-$CASE_ID.pdf"
echo "    saved kyc-report-$CASE_ID.pdf"

echo "==> Done."

#!/usr/bin/env python3
"""
KYC Public API v2 - full onboarding journey (Python + requests)

Journey: token -> search -> create -> poll to Ready -> members + org-chart
         -> get an individual member -> upload document (good vs forged)
         -> AML view -> close (Approved) -> download report PDF

Requires: pip install requests
Usage:    CLIENT_ID=... CLIENT_SECRET=... python journey.py
"""
import os
import sys
import time

import requests

BASE_URL = os.environ.get("BASE_URL", "https://api.knowyourcustomer.dev")  # free Sandbox
CLIENT_ID = os.environ.get("CLIENT_ID", "YOUR_CLIENT_ID")
CLIENT_SECRET = os.environ.get("CLIENT_SECRET", "YOUR_CLIENT_SECRET")

ISO = "GB"
QUERY = "CROPWELL BISHOP"


class KycClient:
    """Minimal client with an in-memory token cache and refresh-on-401."""

    def __init__(self, base_url, client_id, client_secret):
        self.base_url = base_url.rstrip("/")
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._expires_at = 0.0

    def _token_value(self):
        if self._token and time.time() < self._expires_at - 30:
            return self._token
        resp = requests.post(
            f"{self.base_url}/connect/token",
            data={
                "grant_type": "client_credentials",
                "client_id": self.client_id,
                "client_secret": self.client_secret,
                "scope": "PublicApi",
            },
            timeout=30,
        )
        resp.raise_for_status()
        body = resp.json()
        self._token = body["access_token"]
        self._expires_at = time.time() + int(body.get("expires_in", 600))
        return self._token

    def request(self, method, path, **kwargs):
        url = f"{self.base_url}{path}"
        headers = kwargs.pop("headers", {})
        headers["Authorization"] = f"Bearer {self._token_value()}"
        resp = requests.request(method, url, headers=headers, timeout=120, **kwargs)
        if resp.status_code == 401:  # token may have expired mid-journey - refresh once
            self._token = None
            headers["Authorization"] = f"Bearer {self._token_value()}"
            resp = requests.request(method, url, headers=headers, timeout=120, **kwargs)
        return resp


def main():
    client = KycClient(BASE_URL, CLIENT_ID, CLIENT_SECRET)

    # 2. Search the registry
    print(f"==> Searching registry for {QUERY!r} in {ISO}")
    r = client.request("POST", "/v2/Companies/search",
                       json={"codeiso31662": ISO, "query": QUERY})
    r.raise_for_status()
    results = r.json()["companySearch"]["searchResults"]
    if not results:
        sys.exit("No registry results")
    rawname = results[0]["rawname"]
    print(f"    matched: {rawname}")

    # 3. Create the company case
    print("==> Creating company case")
    r = client.request("POST", "/v2/Companies",
                       json={"rawname": rawname, "codeiso31662": ISO})
    r.raise_for_status()
    case_id = r.json()["caseDetail"]["details"]["common"]["caseCommonId"]
    print(f"    caseCommonId: {case_id}")

    # 4. Poll until Ready (statusId == 3)
    print("==> Polling for Ready")
    for _ in range(60):
        r = client.request("GET", f"/v2/Companies/{case_id}")
        r.raise_for_status()
        status = r.json()["caseDetail"]["details"]["common"]["statusId"]
        print(f"    statusId={status}")
        if status == 3:
            break
        if status == 8:
            sys.exit("Case expired/failed")
        time.sleep(5)

    # 5. Members + org-chart
    print("==> Fetching members")
    members = client.request("GET", f"/v2/Companies/{case_id}/members").json()
    controlling = members.get("controllingEntitiesAndIndividuals", [])
    print(f"    controlling parties: {len(controlling)}, "
          f"shareholders: {len(members.get('shareholdersAndBeneficialOwners', []))}")

    print("==> Fetching org-chart (recursive ownership tree)")
    org = client.request("GET", f"/v2/Companies/{case_id}/org-chart").json()

    def walk(node, depth=0):
        print("    " + "  " * depth + f"- {node.get('name')} "
              f"({node.get('effectivePercentage')}%)")
        for child in (node.get("shareholders") or []):
            walk(child, depth + 1)
        for child in (node.get("officers") or []):
            walk(child, depth + 1)

    walk(org)

    # memberType is a STRING ("Individual" / "Company")
    individual = next((m for m in controlling if m.get("memberType") == "Individual"), None)
    if not individual:
        sys.exit("No individual controlling party found")
    indiv_id = individual["member"]["caseCommonId"]
    print(f"    individual member caseCommonId: {indiv_id}")

    # 6. Get the individual + mandatory docs
    print(f"==> Fetching individual member {indiv_id}")
    client.request("GET", f"/v2/Individuals/{indiv_id}").raise_for_status()
    mandatory = client.request(
        "GET", f"/v2/Individuals/{indiv_id}/documents/mandatory").json()
    print(f"    mandatory docs: {mandatory}")  # typically ["photoid","selfie","poa"]

    # 7. Upload a document (multipart) - good then forged
    def upload(file_path, name, label):
        with open(file_path, "rb") as fh:
            r = client.request(
                "POST", f"/v2/Individuals/{indiv_id}/documents/upload",
                data={
                    "name": name,
                    "fileCat": "photoid",
                    "caseCommonId": str(indiv_id),
                    "isCompany": "false",
                },
                files={"file": (os.path.basename(file_path), fh,
                                "application/octet-stream")},
            )
        r.raise_for_status()
        msgs = r.json().get("prevalidationMessages", [])
        print(f"    {label}: prevalidationMessages={msgs}")

    print("==> Uploading a (good) identity document")
    upload("./passport.jpg", "Passport", "good")          # -> []
    print("==> Uploading a (forged) identity document")
    upload("./forged.jpg", "Passport (forged)", "forged")  # -> [{key: IdentityDocumentNotRecognized}]

    # 8. AML view
    print("==> AML checks for the company")
    aml = client.request("GET", f"/v2/Companies/{case_id}/amlchecks").json()
    print(f"    worldChecks={len(aml.get('worldChecks', []))}, "
          f"lexisNexisChecks={len(aml.get('lexisNexisChecks', []))}")

    # 9. Close the case with a decision
    print("==> Recording decision: Approved")
    r = client.request("PATCH", f"/v2/Companies/{case_id}/status",
                       json={"status": "Approved"})
    r.raise_for_status()
    print(f"    {r.json()}")

    # 10. Download the KYC report PDF
    print("==> Downloading KYC report PDF")
    r = client.request("GET", f"/v2/Companies/{case_id}/report",
                       params={"language": "en"})
    if r.status_code == 409:
        sys.exit("Report not ready yet")
    r.raise_for_status()
    out = f"kyc-report-{case_id}.pdf"
    with open(out, "wb") as fh:
        fh.write(r.content)
    print(f"    saved {out}")
    print("==> Done.")


if __name__ == "__main__":
    main()

/**
 * KYC Public API v2 - full onboarding journey (Node / TypeScript, fetch)
 *
 * Journey: token -> search -> create -> poll to Ready -> members + org-chart
 *          -> get an individual member -> upload document (good vs forged)
 *          -> AML view -> close (Approved) -> download report PDF
 *
 * Requires: Node 18+ (built-in fetch, FormData, Blob).
 * Run:      CLIENT_ID=... CLIENT_SECRET=... npx tsx journey.ts
 *           (or compile with `tsc` and run with node)
 */
import { readFile, writeFile } from "node:fs/promises";

const BASE_URL = process.env.BASE_URL ?? "https://api.knowyourcustomer.dev"; // free Sandbox
const CLIENT_ID = process.env.CLIENT_ID ?? "YOUR_CLIENT_ID";
const CLIENT_SECRET = process.env.CLIENT_SECRET ?? "YOUR_CLIENT_SECRET";

const ISO = "GB";
const QUERY = "CROPWELL BISHOP";

/** Minimal client with an in-memory token cache and refresh-on-401. */
class KycClient {
  private token: string | null = null;
  private expiresAt = 0;

  constructor(
    private baseUrl: string,
    private clientId: string,
    private clientSecret: string,
  ) {}

  private async tokenValue(): Promise<string> {
    if (this.token && Date.now() < this.expiresAt - 30_000) return this.token;
    const body = new URLSearchParams({
      grant_type: "client_credentials",
      client_id: this.clientId,
      client_secret: this.clientSecret,
      scope: "PublicApi",
    });
    const res = await fetch(`${this.baseUrl}/connect/token`, { method: "POST", body });
    if (!res.ok) throw new Error(`token failed: ${res.status} ${await res.text()}`);
    const json = (await res.json()) as { access_token: string; expires_in?: number };
    this.token = json.access_token;
    this.expiresAt = Date.now() + (json.expires_in ?? 600) * 1000;
    return this.token;
  }

  async request(method: string, path: string, init: RequestInit = {}): Promise<Response> {
    const headers = new Headers(init.headers);
    headers.set("Authorization", `Bearer ${await this.tokenValue()}`);
    let res = await fetch(`${this.baseUrl}${path}`, { ...init, method, headers });
    if (res.status === 401) {
      // token may have expired mid-journey - refresh once
      this.token = null;
      headers.set("Authorization", `Bearer ${await this.tokenValue()}`);
      res = await fetch(`${this.baseUrl}${path}`, { ...init, method, headers });
    }
    return res;
  }

  async json<T = any>(method: string, path: string, init: RequestInit = {}): Promise<T> {
    const res = await this.request(method, path, init);
    if (!res.ok) throw new Error(`${method} ${path} -> ${res.status} ${await res.text()}`);
    return (await res.json()) as T;
  }
}

interface OrgNode {
  name?: string;
  effectivePercentage?: number | null;
  shareholders?: OrgNode[] | null;
  officers?: OrgNode[] | null;
  others?: OrgNode[] | null;
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main(): Promise<void> {
  const client = new KycClient(BASE_URL, CLIENT_ID, CLIENT_SECRET);

  // 2. Search the registry
  console.log(`==> Searching registry for '${QUERY}' in ${ISO}`);
  const search = await client.json("POST", "/v2/Companies/search", {
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ codeiso31662: ISO, query: QUERY }),
  });
  const rawname: string = search.companySearch.searchResults[0].rawname;
  console.log(`    matched: ${rawname}`);

  // 3. Create the company case
  console.log("==> Creating company case");
  const created = await client.json("POST", "/v2/Companies", {
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ rawname, codeiso31662: ISO }),
  });
  const caseId: number = created.caseDetail.details.common.caseCommonId;
  console.log(`    caseCommonId: ${caseId}`);

  // 4. Poll until Ready (statusId === 3)
  console.log("==> Polling for Ready");
  for (let i = 0; i < 60; i++) {
    const c = await client.json("GET", `/v2/Companies/${caseId}`);
    const status: number = c.caseDetail.details.common.statusId;
    console.log(`    statusId=${status}`);
    if (status === 3) break;
    if (status === 8) throw new Error("Case expired/failed");
    await sleep(5000);
  }

  // 5. Members + org-chart
  console.log("==> Fetching members");
  const members = await client.json("GET", `/v2/Companies/${caseId}/members`);
  const controlling: any[] = members.controllingEntitiesAndIndividuals ?? [];
  console.log(
    `    controlling parties: ${controlling.length}, ` +
      `shareholders: ${(members.shareholdersAndBeneficialOwners ?? []).length}`,
  );

  console.log("==> Fetching org-chart (recursive ownership tree)");
  const org = await client.json<OrgNode>("GET", `/v2/Companies/${caseId}/org-chart`);
  const walk = (node: OrgNode, depth = 0): void => {
    console.log(`    ${"  ".repeat(depth)}- ${node.name} (${node.effectivePercentage}%)`);
    for (const child of node.shareholders ?? []) walk(child, depth + 1);
    for (const child of node.officers ?? []) walk(child, depth + 1);
  };
  walk(org);

  // memberType is a STRING ("Individual" / "Company")
  const individual = controlling.find((m) => m.memberType === "Individual");
  if (!individual) throw new Error("No individual controlling party found");
  const indivId: number = individual.member.caseCommonId;
  console.log(`    individual member caseCommonId: ${indivId}`);

  // 6. Get the individual + mandatory docs
  console.log(`==> Fetching individual member ${indivId}`);
  await client.json("GET", `/v2/Individuals/${indivId}`);
  const mandatory = await client.json("GET", `/v2/Individuals/${indivId}/documents/mandatory`);
  console.log(`    mandatory docs: ${JSON.stringify(mandatory)}`); // ["photoid","selfie","poa"]

  // 7. Upload a document (multipart) - good then forged
  const upload = async (filePath: string, name: string, label: string): Promise<void> => {
    const bytes = await readFile(filePath);
    const form = new FormData();
    form.set("file", new Blob([bytes]), filePath.split("/").pop());
    form.set("name", name);
    form.set("fileCat", "photoid");
    form.set("caseCommonId", String(indivId));
    form.set("isCompany", "false");
    const res = await client.json("POST", `/v2/Individuals/${indivId}/documents/upload`, {
      body: form,
    });
    console.log(`    ${label}: prevalidationMessages=${JSON.stringify(res.prevalidationMessages)}`);
  };

  console.log("==> Uploading a (good) identity document");
  await upload("./passport.jpg", "Passport", "good"); // -> []
  console.log("==> Uploading a (forged) identity document");
  await upload("./forged.jpg", "Passport (forged)", "forged"); // -> [{key:"IdentityDocumentNotRecognized"}]

  // 8. AML view
  console.log("==> AML checks for the company");
  const aml = await client.json("GET", `/v2/Companies/${caseId}/amlchecks`);
  console.log(
    `    worldChecks=${(aml.worldChecks ?? []).length}, ` +
      `lexisNexisChecks=${(aml.lexisNexisChecks ?? []).length}`,
  );

  // 9. Close the case with a decision
  console.log("==> Recording decision: Approved");
  const closed = await client.json("PATCH", `/v2/Companies/${caseId}/status`, {
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ status: "Approved" }),
  });
  console.log(`    ${JSON.stringify(closed)}`);

  // 10. Download the KYC report PDF
  console.log("==> Downloading KYC report PDF");
  const res = await client.request("GET", `/v2/Companies/${caseId}/report?language=en`);
  if (res.status === 409) throw new Error("Report not ready yet");
  if (!res.ok) throw new Error(`report -> ${res.status}`);
  const pdf = Buffer.from(await res.arrayBuffer());
  const out = `kyc-report-${caseId}.pdf`;
  await writeFile(out, pdf);
  console.log(`    saved ${out}`);
  console.log("==> Done.");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});