{ "info": { "_postman_id": "c5b297c1-ffb3-44b2-a4d1-a217f1052192", "name": "Kyboa Client API — Developer examples", "description": "Kyboa v1 developer examples. Set bearer_token privately after importing. Use individual requests deliberately: screening creation consumes credits. Example responses are illustrative. There are no automatic request chains or polling loops. Production origin: https://app.kyboa.com.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{bearer_token}}", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://app.kyboa.com" }, { "key": "api_version", "value": "v1" }, { "key": "bearer_token", "value": "" }, { "key": "request_id", "value": "kyboa-postman-example" }, { "key": "screening_id", "value": "" }, { "key": "entity_id", "value": "" }, { "key": "entity_primary_name", "value": "Acme Pte. Ltd." }, { "key": "entity_jurisdiction", "value": "SG" }, { "key": "entity_registration_number", "value": "202300001A" } ], "item": [ { "name": "Auth", "item": [ { "name": "Get Auth Context", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "X-Request-Id", "value": "{{request_id}}" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/auth/context", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "auth", "context" ] }, "description": "Smoke-test endpoint that returns the authenticated user, account, and full-access token context." }, "response": [ { "name": "200 OK - Auth Context", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "{{request_id}}" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/auth/context", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "auth", "context" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "client-job-20260520-0001" } ], "body": "{\n \"data\": {\n \"user\": {\n \"id\": 456,\n \"email\": \"integration-user@example.com\",\n \"name\": \"Integration User\"\n },\n \"account\": {\n \"id\": 123,\n \"name\": \"Example Client\"\n },\n \"token\": {\n \"id\": 789,\n \"access\": \"full\"\n }\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"client-job-20260520-0001\"\n }\n}" }, { "name": "401 Unauthorized", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/auth/context", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "auth", "context" ] } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "generated-request-id" } ], "body": "{\n \"error\": {\n \"code\": \"UNAUTHENTICATED\",\n \"message\": \"Authentication is required.\",\n \"details\": []\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"generated-request-id\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 200\", function () { pm.response.to.have.status(200); });", "if (pm.response.code === 200) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", "}" ] } } ] } ] }, { "name": "Screenings", "item": [ { "name": "Create Quick Individual Screening", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "client-screening-0001" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"individual\",\n \"name\": \"Jane Doe\",\n \"jurisdiction\": \"sg\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings" ] }, "description": "Creates a quick screening asynchronously and starts the existing pipeline. This endpoint supports quick screenings only." }, "response": [ { "name": "202 Accepted - Created", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "client-screening-0001" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"individual\",\n \"name\": \"Jane Doe\",\n \"jurisdiction\": \"sg\"\n}" }, "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings" ] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "client-screening-0001" } ], "body": "{\n \"data\": {\n \"id\": 1001,\n \"type\": \"individual\",\n \"status\": \"pending\",\n \"primary_subject_name\": \"Jane Doe\",\n \"jurisdiction\": \"SG\",\n \"created_at\": \"2026-05-20T09:30:00+00:00\",\n \"started_at\": null,\n \"completed_at\": null,\n \"app_url\": \"https://app.kyboa.com/individual-screenings/1001\",\n \"poll_path\": \"/api/v1/screenings/1001\",\n \"links\": {\n \"self\": \"/api/v1/screenings/1001\"\n },\n \"primary_subject\": {\n \"id\": 2001,\n \"type\": \"individual\",\n \"name\": \"Jane Doe\",\n \"jurisdiction\": \"SG\"\n },\n \"pipeline\": {\n \"current_step\": null,\n \"progress_percentage\": 0,\n \"degraded\": false,\n \"next_retry_at\": null\n },\n \"final_result\": null\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"client-screening-0001\"\n }\n}" }, { "name": "409 Conflict - Insufficient Screening Balance", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"individual\",\n \"name\": \"Jane Doe\",\n \"jurisdiction\": \"SG\"\n}" }, "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "client-screening-0002" } ], "body": "{\n \"error\": {\n \"code\": \"INSUFFICIENT_SCREENING_BALANCE\",\n \"message\": \"The account does not have enough screening balance remaining.\",\n \"details\": []\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"client-screening-0002\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 202\", function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", " pm.collectionVariables.set(\"screening_id\", String(body.data.id));", "}" ] } } ] }, { "name": "Create Quick Company Screening", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "client-screening-0001" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"company\",\n \"name\": \"Example Trading Pte. Ltd.\",\n \"jurisdiction\": \"SG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings" ] }, "description": "Creates a quick screening asynchronously and starts the existing pipeline. This endpoint supports quick screenings only." }, "response": [ { "name": "202 Accepted - Created", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "client-screening-0001" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"company\",\n \"name\": \"Example Trading Pte. Ltd.\",\n \"jurisdiction\": \"SG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings" ] }, "description": "Creates a quick screening asynchronously and starts the existing pipeline. This endpoint supports quick screenings only." }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "client-screening-0001" } ], "body": "{\n \"data\": {\n \"id\": 1001,\n \"type\": \"company\",\n \"status\": \"pending\",\n \"primary_subject_name\": \"Example Trading Pte. Ltd.\",\n \"jurisdiction\": \"SG\",\n \"created_at\": \"2026-05-20T09:30:00+00:00\",\n \"started_at\": null,\n \"completed_at\": null,\n \"app_url\": \"https://app.kyboa.com/company-screenings/1001\",\n \"poll_path\": \"/api/v1/screenings/1001\",\n \"links\": {\n \"self\": \"/api/v1/screenings/1001\"\n },\n \"primary_subject\": {\n \"id\": 2001,\n \"type\": \"company\",\n \"name\": \"Example Trading Pte. Ltd.\",\n \"jurisdiction\": \"SG\"\n },\n \"pipeline\": {\n \"current_step\": null,\n \"progress_percentage\": 0,\n \"degraded\": false,\n \"next_retry_at\": null\n },\n \"final_result\": null\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"client-screening-0001\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 202\", function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", " pm.collectionVariables.set(\"screening_id\", String(body.data.id));", "}" ] } } ] }, { "name": "Poll Screening", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "X-Request-Id", "value": "screening-poll-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings/{{screening_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings", "{{screening_id}}" ] }, "description": "Canonical polling endpoint for quick screenings. Update screening_id after you create a screening." }, "response": [ { "name": "200 OK - In Progress", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "screening-poll-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings/{{screening_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings", "{{screening_id}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "screening-poll-0001" } ], "body": "{\n \"data\": {\n \"id\": 1001,\n \"type\": \"individual\",\n \"status\": \"running\",\n \"primary_subject_name\": \"Jane Doe\",\n \"jurisdiction\": \"SG\",\n \"created_at\": \"2026-05-20T09:30:00+00:00\",\n \"started_at\": \"2026-05-20T09:30:03+00:00\",\n \"completed_at\": null,\n \"app_url\": \"https://app.kyboa.com/individual-screenings/1001\",\n \"poll_path\": \"/api/v1/screenings/1001\",\n \"links\": {\n \"self\": \"/api/v1/screenings/1001\"\n },\n \"primary_subject\": {\n \"id\": 2001,\n \"type\": \"individual\",\n \"name\": \"Jane Doe\",\n \"jurisdiction\": \"SG\"\n },\n \"pipeline\": {\n \"current_step\": \"web\",\n \"progress_percentage\": 50,\n \"degraded\": false,\n \"next_retry_at\": null\n },\n \"final_result\": null\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"screening-poll-0001\"\n }\n}" }, { "name": "200 OK - Completed", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "screening-poll-0002" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings/{{screening_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings", "{{screening_id}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "screening-poll-0002" } ], "body": "{\n \"data\": {\n \"id\": 1001,\n \"type\": \"individual\",\n \"status\": \"completed\",\n \"primary_subject_name\": \"Jane Doe\",\n \"jurisdiction\": \"SG\",\n \"created_at\": \"2026-05-20T09:30:00+00:00\",\n \"started_at\": \"2026-05-20T09:30:03+00:00\",\n \"completed_at\": \"2026-05-20T09:35:20+00:00\",\n \"app_url\": \"https://app.kyboa.com/individual-screenings/1001\",\n \"poll_path\": \"/api/v1/screenings/1001\",\n \"links\": {\n \"self\": \"/api/v1/screenings/1001\"\n },\n \"primary_subject\": {\n \"id\": 2001,\n \"type\": \"individual\",\n \"name\": \"Jane Doe\",\n \"jurisdiction\": \"SG\"\n },\n \"pipeline\": {\n \"current_step\": \"report\",\n \"progress_percentage\": 100,\n \"degraded\": false,\n \"next_retry_at\": null\n },\n \"final_result\": {\n \"risk_rating\": \"low\",\n \"risk_rating_label\": \"Low (Green)\",\n \"confidence_level\": \"high\",\n \"confidence_level_label\": \"High\",\n \"report\": {\n \"id\": 3001,\n \"type\": \"individual_v2_2\",\n \"format\": \"markdown\",\n \"generated_at\": \"2026-05-20T09:35:20+00:00\"\n }\n }\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"screening-poll-0002\"\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/screenings/999999", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "screenings", "999999" ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "screening-poll-0003" } ], "body": "{\n \"error\": {\n \"code\": \"NOT_FOUND\",\n \"message\": \"The requested resource was not found.\",\n \"details\": []\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"screening-poll-0003\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 200\", function () { pm.response.to.have.status(200); });", "if (pm.response.code === 200) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", "}" ] } } ] } ] }, { "name": "Entities", "item": [ { "name": "Check Existing Entity", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-check-0001" } ], "body": { "mode": "raw", "raw": "{\n \"entity_type\": \"company\",\n \"jurisdiction\": \"sg\",\n \"primary_name\": \"{{entity_primary_name}}\",\n \"registration_number\": \"{{entity_registration_number}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/check-existing", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "check-existing" ] }, "description": "Checks whether a same-account Entity already exists using registration number or normalized name matching." }, "response": [ { "name": "200 OK - No Match", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "entity-check-0001" } ], "body": { "mode": "raw", "raw": "{\n \"entity_type\": \"company\",\n \"jurisdiction\": \"sg\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"registration_number\": \"202300001A\"\n}" }, "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/check-existing", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "check-existing" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-check-0001" } ], "body": "{\n \"data\": {\n \"exists\": false,\n \"match_type\": null,\n \"entity\": null\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-check-0001\"\n }\n}" }, { "name": "200 OK - Duplicate Exists", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "entity-check-0002" } ], "body": { "mode": "raw", "raw": "{\n \"entity_type\": \"company\",\n \"jurisdiction\": \"sg\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"registration_number\": \"202300001A\"\n}" }, "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/check-existing", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "check-existing" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-check-0002" } ], "body": "{\n \"data\": {\n \"exists\": true,\n \"match_type\": \"registration_number\",\n \"entity\": {\n \"id\": 4001,\n \"entity_type\": \"company\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"SG\",\n \"registration_number\": \"202300001A\",\n \"app_url\": \"https://app.kyboa.com/entities/4001\"\n }\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-check-0002\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 200\", function () { pm.response.to.have.status(200); });", "if (pm.response.code === 200) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", " if (body.data.exists) pm.collectionVariables.set(\"entity_id\", String(body.data.entity.id)); else pm.collectionVariables.unset(\"entity_id\");", "}" ] } } ] }, { "name": "Create Minimal Entity", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-create-0001" } ], "body": { "mode": "raw", "raw": "{\n \"entity_type\": \"company\",\n \"primary_name\": \"{{entity_primary_name}}\",\n \"jurisdiction\": \"sg\",\n \"registration_number\": \"{{entity_registration_number}}\",\n \"monitoring_frequency\": \"monthly\",\n \"notes\": \"Imported from client onboarding system\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/{{api_version}}/entities", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities" ] }, "description": "Creates a minimal manual Entity through the shared Entity write service. This endpoint is create-only and does not auto-run a screening." }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "entity-create-0001" } ], "body": { "mode": "raw", "raw": "{\n \"entity_type\": \"company\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"sg\",\n \"registration_number\": \"202300001A\",\n \"monitoring_frequency\": \"monthly\",\n \"notes\": \"Imported from client onboarding system\"\n}" }, "url": { "raw": "{{base_url}}/api/{{api_version}}/entities", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-create-0001" } ], "body": "{\n \"data\": {\n \"id\": 4001,\n \"entity_type\": \"company\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"SG\",\n \"registration_number\": \"202300001A\",\n \"monitoring_frequency\": \"monthly\",\n \"app_url\": \"https://app.kyboa.com/entities/4001\",\n \"created_at\": \"2026-05-20T10:15:00+00:00\"\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-create-0001\"\n }\n}" }, { "name": "409 Conflict - Entity Already Exists", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "entity-create-0002" } ], "body": { "mode": "raw", "raw": "{\n \"entity_type\": \"company\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"sg\",\n \"registration_number\": \"202300001A\",\n \"monitoring_frequency\": \"monthly\",\n \"notes\": \"Imported from client onboarding system\"\n}" }, "url": { "raw": "{{base_url}}/api/{{api_version}}/entities", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-create-0002" } ], "body": "{\n \"error\": {\n \"code\": \"ENTITY_ALREADY_EXISTS\",\n \"message\": \"An Entity matching the submitted identity already exists in this account.\",\n \"details\": {\n \"match_type\": \"registration_number\",\n \"entity\": {\n \"id\": 4001,\n \"entity_type\": \"company\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"SG\",\n \"registration_number\": \"202300001A\",\n \"app_url\": \"https://app.kyboa.com/entities/4001\"\n }\n }\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-create-0002\"\n }\n}" }, { "name": "422 Unprocessable Entity - Validation Error", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" } ], "body": { "mode": "raw", "raw": "{}" }, "url": { "raw": "{{base_url}}/api/{{api_version}}/entities", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities" ] } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-create-0003" } ], "body": "{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"The given data was invalid.\",\n \"details\": {\n \"errors\": {\n \"entity_type\": [\n \"The entity type field is required.\"\n ],\n \"primary_name\": [\n \"The primary name field is required.\"\n ],\n \"jurisdiction\": [\n \"The jurisdiction field is required.\"\n ]\n }\n }\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-create-0003\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 201\", function () { pm.response.to.have.status(201); });", "if (pm.response.code === 201) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", " pm.collectionVariables.set(\"entity_id\", String(body.data.id));", "}" ] } } ] }, { "name": "Read Entity Detail", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-detail-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/{{entity_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "{{entity_id}}" ] }, "description": "Returns the full current-state Entity detail for a same-account Entity. Includes core identity, company or individual details, contact and notes, monitoring, metadata, names, addresses, associated people, corporate shareholders, and shareholder references. Nested collections intentionally omit child row IDs, sort order, source markers, source table, and source row IDs. Does not embed screening history, version history, review decisions, raw registry artifacts, or report content." }, "response": [ { "name": "200 OK - Entity Detail", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "entity-detail-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/{{entity_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "{{entity_id}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-detail-0001" } ], "body": "{\n \"data\": {\n \"id\": 4001,\n \"entity_type\": \"company\",\n \"status\": \"active\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"SG\",\n \"registration_number\": \"202300001A\",\n \"monitoring_frequency\": \"monthly\",\n \"app_url\": \"https://app.kyboa.com/entities/4001\",\n \"core_identity\": {\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"entity_type\": \"company\",\n \"status\": \"active\",\n \"jurisdiction\": \"SG\"\n },\n \"company_details\": {\n \"registration_number\": \"202300001A\",\n \"previous_registration_number\": null,\n \"tax_number\": null,\n \"vat_number\": null,\n \"license_number\": null,\n \"entity_legal_form\": \"Private Company Limited by Shares\",\n \"registration_status\": \"Registered\",\n \"incorporation_date\": \"2024-01-15\",\n \"dissolution_date\": null,\n \"business_activities\": \"Software services\"\n },\n \"individual_details\": null,\n \"contact_and_notes\": {\n \"website\": \"https://acme.example\",\n \"email\": \"compliance@acme.example\",\n \"phone\": \"+65 5555 0000\",\n \"notes\": \"Imported from client onboarding system\",\n \"source_summary\": \"manual_entry\"\n },\n \"monitoring\": {\n \"frequency\": \"monthly\",\n \"last_screened_at\": \"2026-05-20T10:25:20+00:00\",\n \"monitoring_last_run_at\": \"2026-05-20T10:25:20+00:00\",\n \"next_monitoring_due_at\": \"2026-06-20T10:25:20+00:00\"\n },\n \"metadata\": {\n \"created_by\": {\n \"id\": 456,\n \"name\": \"Integration User\"\n },\n \"created_at\": \"2026-05-20T10:15:00+00:00\",\n \"updated_by\": null,\n \"updated_at\": \"2026-05-20T10:15:00+00:00\"\n },\n \"additional_names\": [],\n \"addresses\": [],\n \"associated_people\": [],\n \"corporate_shareholders\": [],\n \"shareholders\": [],\n \"links\": {\n \"self\": \"/api/v1/entities/4001\",\n \"screenings\": \"/api/v1/entities/4001/screenings\"\n }\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-detail-0001\"\n }\n}" }, { "name": "404 Not Found - Missing or Cross-Account Entity", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/999999", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "999999" ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-detail-0002" } ], "body": "{\n \"error\": {\n \"code\": \"NOT_FOUND\",\n \"message\": \"The requested resource was not found.\",\n \"details\": []\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-detail-0002\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 200\", function () { pm.response.to.have.status(200); });", "if (pm.response.code === 200) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", "}" ] } } ] }, { "name": "Trigger Entity Screening", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-screening-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/{{entity_id}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "{{entity_id}}", "screenings" ] }, "description": "Explicitly creates a screening from the current Entity data through the shared Entity screening action. This endpoint has no request body; Entity creation itself does not auto-run a screening. Requires a valid full-access API token." }, "response": [ { "name": "202 Accepted - Entity Screening Created", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "entity-screening-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/{{entity_id}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "{{entity_id}}", "screenings" ] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-screening-0001" } ], "body": "{\n \"data\": {\n \"id\": 1002,\n \"type\": \"company\",\n \"status\": \"pending\",\n \"primary_subject_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"SG\",\n \"created_at\": \"2026-05-20T10:20:00+00:00\",\n \"started_at\": null,\n \"completed_at\": null,\n \"app_url\": \"https://app.kyboa.com/company-screenings/1002\",\n \"poll_path\": \"/api/v1/screenings/1002\",\n \"links\": {\n \"self\": \"/api/v1/screenings/1002\"\n },\n \"primary_subject\": {\n \"id\": 2002,\n \"type\": \"company\",\n \"name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"SG\"\n },\n \"pipeline\": {\n \"current_step\": null,\n \"progress_percentage\": 0,\n \"degraded\": false,\n \"next_retry_at\": null\n },\n \"final_result\": null\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-screening-0001\"\n }\n}" }, { "name": "404 Not Found - Missing or Cross-Account Entity", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/999999/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "999999", "screenings" ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-screening-0002" } ], "body": "{\n \"error\": {\n \"code\": \"NOT_FOUND\",\n \"message\": \"The requested resource was not found.\",\n \"details\": []\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-screening-0002\"\n }\n}" }, { "name": "409 Conflict - Insufficient Screening Balance", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/{{entity_id}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "{{entity_id}}", "screenings" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-screening-0003" } ], "body": "{\n \"error\": {\n \"code\": \"INSUFFICIENT_SCREENING_BALANCE\",\n \"message\": \"The account does not have enough screening balance remaining.\",\n \"details\": []\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-screening-0003\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 202\", function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", " pm.collectionVariables.set(\"screening_id\", String(body.data.id));", "}" ] } } ] }, { "name": "List Entity Screening History", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-history-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/{{entity_id}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "{{entity_id}}", "screenings" ] }, "description": "Returns compact newest-first screening history rows linked to an Entity. Includes manual Entity screenings and monitoring-created screenings. Requires a valid full-access API token." }, "response": [ { "name": "200 OK - Screening History", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" }, { "key": "X-Request-Id", "value": "entity-history-0001" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/{{entity_id}}/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "{{entity_id}}", "screenings" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-history-0001" } ], "body": "{\n \"data\": {\n \"entity\": {\n \"id\": 4001,\n \"entity_type\": \"company\",\n \"primary_name\": \"Acme Pte. Ltd.\",\n \"jurisdiction\": \"SG\",\n \"registration_number\": \"202300001A\",\n \"app_url\": \"https://app.kyboa.com/entities/4001\"\n },\n \"screenings\": [\n {\n \"id\": 1002,\n \"type\": \"company\",\n \"trigger_type\": \"entity_manual\",\n \"status\": \"completed\",\n \"created_at\": \"2026-05-20T10:20:00+00:00\",\n \"started_at\": \"2026-05-20T10:20:03+00:00\",\n \"completed_at\": \"2026-05-20T10:25:20+00:00\",\n \"risk_rating\": \"low\",\n \"confidence_level\": \"high\",\n \"app_url\": \"https://app.kyboa.com/company-screenings/1002\",\n \"detail_path\": \"/api/v1/screenings/1002\",\n \"links\": {\n \"self\": \"/api/v1/screenings/1002\"\n }\n },\n {\n \"id\": 1001,\n \"type\": \"company\",\n \"trigger_type\": \"entity_monitoring\",\n \"status\": \"completed_degraded\",\n \"created_at\": \"2026-05-19T10:20:00+00:00\",\n \"started_at\": \"2026-05-19T10:20:03+00:00\",\n \"completed_at\": \"2026-05-19T10:25:20+00:00\",\n \"risk_rating\": \"medium\",\n \"confidence_level\": \"medium\",\n \"app_url\": \"https://app.kyboa.com/company-screenings/1001\",\n \"detail_path\": \"/api/v1/screenings/1001\",\n \"links\": {\n \"self\": \"/api/v1/screenings/1001\"\n }\n }\n ]\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-history-0001\"\n }\n}" }, { "name": "404 Not Found - Missing or Cross-Account Entity", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{bearer_token}}" } ], "url": { "raw": "{{base_url}}/api/{{api_version}}/entities/999999/screenings", "host": [ "{{base_url}}" ], "path": [ "api", "{{api_version}}", "entities", "999999", "screenings" ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "entity-history-0002" } ], "body": "{\n \"error\": {\n \"code\": \"NOT_FOUND\",\n \"message\": \"The requested resource was not found.\",\n \"details\": []\n },\n \"meta\": {\n \"api_version\": \"v1\",\n \"request_id\": \"entity-history-0002\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"HTTP 200\", function () { pm.response.to.have.status(200); });", "if (pm.response.code === 200) {", " const body = pm.response.json();", " pm.test(\"Versioned JSON envelope\", function () { pm.expect(body.meta.api_version).to.eql(\"v1\"); pm.expect(body.meta.request_id).to.be.a(\"string\"); });", "}" ] } } ] } ] } ] }