{ "openapi": "3.1.1", "info": { "title": "Policy365 Sanctions Screening", "description": "Screens people and companies against the UK, EU, UN, US and Canadian sanctions lists, and looks UK companies up at Companies House with their directors and owners. Two verbs: /api/lookup (free; nothing screened) and /api/screen (recorded, signed, 3p a name). Every call needs the caller's key in the X-Api-Key header; /health alone needs none. POST /api/screen answers 200 with each subject clear, review or match, 400 for a wrong request, and 503 when the lists aren't all current or the screening couldn't be recorded (not screened). Webhooks (below) tell your systems of re-check hits and decisions; add an address with POST /api/webhooks.", "contact": { "name": "Policy365 support", "url": "https://policy365.ca/docs", "email": "support@policy365.cloud" }, "version": "v1" }, "servers": [ { "url": "https://policy365.ca/" } ], "paths": { "/health": { "get": { "tags": [ "Service" ], "summary": "Whether the service may screen: 200 when every list is current, 503 when not. No key needed.", "operationId": "health", "responses": { "200": { "description": "OK" } } } }, "/api/screen/company": { "post": { "tags": [ "Screening" ], "summary": "A company screened from its name alone, for underwriting in the background. When exactly one active company has\nthe name given (case, punctuation, \"The\", \"&\"/\"and\", Son/Sons, Brother/Brothers, Farm/Farms, spaced initials and\nthe legal form aside), it is screened with its officers and controllers: resolution \"matched\", status the\nscreening's. Otherwise resolution \"ambiguous\" or \"notFound\", status \"notScreened\", and the candidates to choose\nfrom, each screened by POST /api/screen/company/{number}. Always 200 with an answer; 400, 502 and 503 only when\nsomething is wrong.", "operationId": "screenCompanyByName", "requestBody": { "description": "Cancelled if the caller goes away.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAnswer" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screen/company/csv": { "get": { "tags": [ "Screening" ], "summary": "The same check as POST /api/screen/company, answered as CSV for MS Access: a header row, then the people screened\nwhen matched, a \"choose\" row for each candidate when ambiguous, or one \"notScreened\" row when not found.", "operationId": "screenCompanyByNameCsv", "parameters": [ { "name": "name", "in": "query", "description": "The company's name, as the proposer gave it.", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "description": "The caller's own reference, returned on every row.", "schema": { "type": "string" } }, { "name": "disqualifications", "in": "query", "description": "Whether to check each officer against the disqualified register too.", "schema": { "type": "boolean" } }, { "name": "watch", "in": "query", "description": "When matched, whether to keep watching them; not given, as the account's plan says.", "schema": { "type": "boolean" } }, { "name": "watchMonths", "in": "query", "description": "For how long, 1 to 120 months; 12 if not given.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "groupReference", "in": "query", "description": "The policy, quote or case this is for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" } }, "text/plain": { } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/lookup": { "get": { "tags": [ "Lookup" ], "summary": "Companies matching a name or number, from Companies House: each with its company number, which is what to keep\non a client's record and screen by. Looked up only: nothing is screened, and nothing is billed.", "operationId": "lookupCompanies", "parameters": [ { "name": "q", "in": "query", "description": "A name, or part of one, or a company number; two characters at least.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/lookup/{number}": { "get": { "tags": [ "Lookup" ], "summary": "A company's profile, officers in office and persons with significant control, from Companies House. Looked up\nonly: nothing is screened, and nothing is billed. To screen them, POST /api/screen/company/{number}.", "operationId": "lookupCompany", "parameters": [ { "name": "number", "in": "path", "description": "The company number, such as 00445790 or SC296753.", "required": true, "schema": { "type": "string" } }, { "name": "disqualifications", "in": "query", "description": "Whether to check each officer against the disqualified register too (an extra call or more for each).", "schema": { "type": "boolean" } }, { "name": "current", "in": "query", "description": "Only roles held now (true, the default), or former ones too (false).", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCompanyAnswer" }, "example": { "company": { "companyNumber": "SC123456", "name": "GLEN AFFRIC FARMS LTD", "status": "active", "type": "ltd", "created": "2010-01-01", "dissolved": null, "registeredOffice": { "premises": null, "line1": "1 High Street", "line2": null, "locality": "Inverness", "region": null, "postalCode": "IV1 1AA", "country": "Scotland" }, "sicCodes": [ "01410" ], "previousNames": [ { "name": "AFFRIC LAMB LTD", "from": "2010-01-01", "until": "2015-06-30" } ] }, "people": [ { "personId": 123, "officerId": "Xk8…", "kind": "person", "name": "Fiona MACLEOD", "birthYear": 1975, "birthMonth": 6, "nationality": "British", "countryOfResidence": "Scotland", "occupation": "Farmer", "companyNumber": null, "appointments": [ { "type": "director", "from": "2015-01-01", "until": null }, { "type": "personWithSignificantControl", "from": "2016-04-06", "until": null, "naturesOfControl": [ "ownership-of-shares-75-to-100-percent" ] } ], "disqualifications": null }, { "personId": 124, "officerId": null, "kind": "company", "name": "AFFRIC HOLDINGS LTD", "companyNumber": "SC654321", "appointments": [ { "type": "corporateDirector", "from": "2012-03-01", "until": "2018-09-30" } ] } ], "withheld": 0, "asOf": "2026-10-16T22:40:00+00:00" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screen/company/{number}": { "post": { "tags": [ "Screening" ], "summary": "Screens a company with its officers in office and persons with significant control, from Companies House, as one\nrecorded screening. 404 if Companies House has no such company, 502 if it can't answer: not screened.", "operationId": "screenCompany", "parameters": [ { "name": "number", "in": "path", "description": "The company number.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Cancelled if the caller goes away.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompanyScreenRequest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screen/company/{number}/csv": { "get": { "tags": [ "Screening" ], "summary": "The same check as POST /api/screen/company/{number}, answered as CSV for MS Access: a header row, then a row for\nthe company and for each officer and controller; any failure is one line of plain text.", "operationId": "screenCompanyCsv", "parameters": [ { "name": "number", "in": "path", "description": "The company number.", "required": true, "schema": { "type": "string" } }, { "name": "reference", "in": "query", "description": "The caller's own reference, kept with the record and returned on every row.", "schema": { "type": "string" } }, { "name": "disqualifications", "in": "query", "description": "Whether to check each officer against the disqualified register too.", "schema": { "type": "boolean" } }, { "name": "watch", "in": "query", "description": "Whether to keep watching them; not given, as the account's plan says.", "schema": { "type": "boolean" } }, { "name": "watchMonths", "in": "query", "description": "For how long, 1 to 120 months; 12 if not given.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "groupReference", "in": "query", "description": "The policy, quote or case this is for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" } }, "text/plain": { } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/watches": { "get": { "tags": [ "Watches" ], "summary": "The account's watches: those running now, or with all=true every one, ended and lapsed too. Newest first, at most 500.", "operationId": "listWatches", "parameters": [ { "name": "all", "in": "query", "description": "Ended and lapsed watches too.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchList" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/watches/{watchId}": { "delete": { "tags": [ "Watches" ], "summary": "A watch ended: no more re-checks. 204, or 404 when it isn't one of the account's running watches.", "operationId": "endWatch", "parameters": [ { "name": "watchId", "in": "path", "description": "The watch, as the list gives it.", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "No Content", "content": { "application/json": { } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/lookup/person/{personId}": { "get": { "tags": [ "Lookup" ], "summary": "A person, or a company holding roles, with every role they hold or held, newest last. 404 if there's no such ID. Free.", "operationId": "lookupPerson", "parameters": [ { "name": "personId", "in": "path", "description": "The register's ID, as a company lookup or a screening's subject gives it.", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterPerson" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screen": { "post": { "tags": [ "Screening" ], "summary": "Screens the subjects given. A company given with its companyNumber has its officers and persons with\nsignificant control screened too, from Companies House.", "operationId": "screen", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenRequest" }, "example": { "groupReference": "Q-10234", "subjects": [ { "id": "firm", "name": "Highland Lamb Co Ltd", "kind": "company", "role": "proposer" }, { "id": "p1", "name": "Fiona MacLeod", "kind": "person", "birthYear": 1975, "birthMonth": 6, "role": "principal" }, { "id": "p2", "name": "Oleg Deripaska", "kind": "person", "birthYear": 1968, "birthMonth": 1, "role": "principal" } ] } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" }, "example": { "groupReference": "Q-10234", "screeningId": "fb44353e-6b0e-4c8e-9f0a-2d3b5c7e9a10", "screenedAt": "2026-10-18T17:42:01.123+00:00", "status": "match", "lists": [ { "source": "uk", "title": "UK Sanctions List", "loaded": true, "current": true, "generated": "2026-10-17T09:00:00+00:00", "downloadedAt": "2026-10-18T03:00:12+00:00", "checkedAt": "2026-10-18T15:00:03+00:00", "fingerprint": "067e24b1…", "parties": 6408 } ], "thresholds": { "match": 0.9, "review": 0.7 }, "subjects": [ { "subjectId": "firm", "name": "Highland Lamb Co Ltd", "kind": "company", "role": "proposer", "companyNumber": null, "status": "clear", "score": 0, "matchedName": null, "datasets": [ ], "matches": [ ], "disqualifications": null }, { "subjectId": "p1", "name": "Fiona MacLeod", "kind": "person", "role": "principal", "companyNumber": null, "status": "clear", "score": 0, "matchedName": null, "datasets": [ ], "matches": [ ], "disqualifications": null, "birthYear": 1975, "birthMonth": 6 }, { "subjectId": "p2", "name": "Oleg Deripaska", "kind": "person", "role": "principal", "companyNumber": null, "status": "match", "score": 1, "matchedName": "Oleg DERIPASKA", "datasets": [ "uk" ], "matches": [ { "source": "uk", "listId": "RUS0269", "caption": "Oleg Vladimirovich DERIPASKA", "matchedName": "Oleg DERIPASKA", "score": 1, "nameScore": 1, "birthYearRuledOut": false, "regime": "The Russia (Sanctions) (EU Exit) Regulations 2019" } ], "disqualifications": null, "birthYear": 1968, "birthMonth": 1 } ], "companies": [ ], "unscreened": [ ], "watchedUntil": null, "units": { "screenings": 3, "companyChecks": 0, "disqualificationChecks": 0, "billed": 3 }, "verifyCode": "ZNWV-EVQA-BSTV", "verifyUrl": "https://screening.policy365.cloud/verify?code=ZNWV-EVQA-BSTV", "notice": "An automated comparison with the sanctions lists as last fetched. A review or a match means a name resembles a listed entry, for a person to look at: it is not a finding that anyone is sanctioned, and not legal advice." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screen/csv": { "get": { "tags": [ "Screening" ], "summary": "Screens one subject given in the query and answers CSV: a header row and one data row (see ScreeningCsv). For\ncallers such as MS Access through VBA. 400 and 503 answer one line of plain text saying why; anything but 200\nis not screened.", "operationId": "screenCsv", "parameters": [ { "name": "type", "in": "query", "description": "\"person\" or \"company\".", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "The name to screen.", "schema": { "type": "string" } }, { "name": "dob", "in": "query", "description": "The date of birth where known, as yyyy, yyyy-mm or yyyy-mm-dd; only the year and month are used.", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "description": "The caller's own reference, kept with the record.", "schema": { "type": "string" } }, { "name": "groupReference", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" } }, "text/plain": { } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screenings/{id}": { "get": { "tags": [ "Records" ], "summary": "A recorded screening: who asked, when, against which lists, the request and the answer.", "operationId": "getScreening", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordedScreening" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screenings/{id}/decisions": { "post": { "tags": [ "Records" ], "summary": "Records a decision on a review: whether a subject of a screening is the listed entry it resembled. \"notThem\"\nclears that entry for that person in every later screening by this account, until the entry changes; \"isThem\"\nmakes it a match whatever its score; \"withdrawn\" undoes the last decision. A reason and the name of the person\nwho decided are needed: the key isn't a person. Free.", "operationId": "recordDecision", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Decision" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] }, "get": { "tags": [ "Records" ], "summary": "The decisions recorded on a screening, oldest first.", "operationId": "listDecisions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/lists": { "get": { "tags": [ "Service" ], "summary": "Each list's state, and whether the service may screen.", "operationId": "lists", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListsAnswer" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "The account's running addresses.", "operationId": "listWebhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "security": [ { "ApiKey": [ ] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "An address added: 201 with its id and its signing secret, given this once. 400 says what's wrong.", "operationId": "addWebhook", "requestBody": { "description": "Cancelled if the caller goes away.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAdded" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks/{webhookId}": { "delete": { "tags": [ "Webhooks" ], "summary": "An address switched off: 204, or 404 when it isn't one of the account's running addresses.", "operationId": "removeWebhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks/{webhookId}/test": { "post": { "tags": [ "Webhooks" ], "summary": "A webhook.test event, to one address now: 202, or 404.", "operationId": "testWebhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "202": { "description": "Accepted" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "The account's recent deliveries, newest first: at most 50, kept 90 days.", "operationId": "listDeliveries", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks/deliveries/{deliveryId}/resend": { "post": { "tags": [ "Webhooks" ], "summary": "A delivery sent again now, as the same event: 202, or 404.", "operationId": "resendDelivery", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Accepted" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } } }, "components": { "schemas": { "Address": { "required": [ "premises", "line1", "line2", "locality", "region", "postalCode", "country" ], "type": "object", "properties": { "premises": { "type": [ "null", "string" ] }, "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "locality": { "type": [ "null", "string" ] }, "region": { "type": [ "null", "string" ] }, "postalCode": { "type": [ "null", "string" ] }, "country": { "type": [ "null", "string" ] } }, "description": "An address, line by line, as Companies House holds it." }, "CallUnits": { "required": [ "screenings", "companyChecks", "disqualificationChecks", "billed" ], "type": "object", "properties": { "screenings": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "People and companies screened, given or added from Companies House: billed.", "format": "int32" }, "companyChecks": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Companies looked up at Companies House: counted, not billed.", "format": "int32" }, "disqualificationChecks": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Officers checked against the disqualified register: billed.", "format": "int32" }, "billed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The units billed: screenings and disqualification checks.", "format": "int32" } }, "description": "What a call billed, at 3p a unit." }, "CheckAnswer": { "required": [ "units", "verifyCode", "verifyUrl" ], "type": "object", "properties": { "resolution": { "description": "Matched, ambiguous or notFound.", "$ref": "#/components/schemas/CheckResolution" }, "status": { "enum": [ "clear", "review", "match", "notScreened" ], "type": "string", "description": "The screening's status when matched (clear, review, match); otherwise notScreened." }, "name": { "type": "string", "description": "The name given." }, "reference": { "type": [ "null", "string" ], "description": "The caller's reference, as given." }, "company": { "oneOf": [ { "type": "null" }, { "description": "The company found, when matched.", "$ref": "#/components/schemas/CompanySummary" } ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyCandidate" }, "description": "When not matched, what the search found, best first." }, "screening": { "oneOf": [ { "type": "null" }, { "description": "The screening, when matched: the same as POST /api/screen's answer, and recorded the same way.", "$ref": "#/components/schemas/ScreenResponse" } ] }, "recordId": { "type": "string", "description": "The check's record, found by /api/screenings/{id}: the screening's when matched, else the check's own - a referral is a decision too.", "format": "uuid" }, "watchedUntil": { "type": [ "null", "string" ], "description": "When matched and watched: until when the company, its officers and controllers are watched; else null.", "format": "date-time" }, "units": { "description": "What the call billed: nothing unless the company was matched and screened.", "$ref": "#/components/schemas/CallUnits" }, "verifyCode": { "type": [ "null", "string" ], "description": "The record's verification code: the screening's when matched, else the check's own." }, "verifyUrl": { "type": [ "null", "string" ], "description": "The link that checks the record." }, "notice": { "type": "string", "description": "What a result is and isn't, for any system that shows it to a person (decided 17 October 2026)." } }, "description": "A company check's answer, with what the call billed and how to verify the record." }, "CheckResolution": { "enum": [ "matched", "ambiguous", "notFound" ], "type": "string", "description": "How the company was found." }, "CompanyCandidate": { "required": [ "companyNumber", "name", "companyStatus", "type", "created", "address", "score", "sameName" ], "type": "object", "properties": { "companyNumber": { "type": "string", "description": "Its number, to screen it by with /api/companies/{number}/screen." }, "name": { "type": "string", "description": "Its registered name." }, "companyStatus": { "type": [ "null", "string" ], "description": "Active, dissolved, liquidation..." }, "type": { "type": [ "null", "string" ], "description": "Its type (ltd, plc, llp...)." }, "created": { "type": [ "null", "string" ], "description": "When incorporated." }, "address": { "type": [ "null", "string" ], "description": "Its registered office." }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "description": "How alike its name is to the name given, 0 to 1.", "format": "double" }, "sameName": { "type": "boolean", "description": "Whether its name is the name given, but for case, punctuation and legal form." } }, "description": "A company the search found, for a person to choose from." }, "CompanyCheckRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "The company's name, as the proposer gave it." }, "reference": { "type": [ "null", "string" ], "description": "The caller's own reference, kept with the record." }, "disqualifications": { "type": "boolean", "description": "Whether to check each officer against the disqualified register too.", "default": false }, "watch": { "type": [ "null", "boolean" ], "description": "When matched, whether to keep watching the company, its officers and its controllers, re-checked each time a list\n changes, as on /api/screen: for an account whose plan includes re-screening. Not given: as the plan says (not watched,\n unless it watches everything)." }, "watchMonths": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "For how long, 1 to 120 months; 12 if not given. Watching someone already watched renews it.", "format": "int32" }, "groupReference": { "type": [ "null", "string" ], "description": "The policy, quote or case it belongs to. Given, \"reference\" is the company's own reference; not given, \"reference\" is taken as the group's, as before." }, "monitor": { "type": [ "null", "boolean" ], "description": "The old name of watch: still taken for now, and going. Use watch.", "deprecated": true }, "monitorMonths": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The old name of watchMonths: still taken for now, and going. Use watchMonths.", "format": "int32", "deprecated": true } }, "description": "A company check's request." }, "CompanyLookup": { "required": [ "profile", "officers", "controllers", "disqualificationsChecked", "lookedUpAt" ], "type": "object", "properties": { "profile": { "description": "The profile.", "$ref": "#/components/schemas/CompanyProfile" }, "officers": { "type": "array", "items": { "$ref": "#/components/schemas/Officer" }, "description": "The officers in office." }, "controllers": { "type": "array", "items": { "$ref": "#/components/schemas/Controller" }, "description": "The persons with significant control still notified." }, "disqualificationsChecked": { "type": "boolean", "description": "Whether each officer was checked against the disqualified register." }, "lookedUpAt": { "type": "string", "description": "When.", "format": "date-time" } }, "description": "Everything looked up for one company." }, "CompanyProfile": { "required": [ "companyNumber", "name", "status", "type", "created", "registeredOffice", "sicCodes" ], "type": "object", "properties": { "companyNumber": { "type": "string" }, "name": { "type": "string" }, "status": { "type": [ "null", "string" ] }, "type": { "type": [ "null", "string" ] }, "created": { "type": [ "null", "string" ] }, "registeredOffice": { "type": [ "null", "string" ] }, "sicCodes": { "type": "array", "items": { "type": "string" } }, "dissolved": { "type": [ "null", "string" ], "description": "When it ceased, where it has." }, "office": { "oneOf": [ { "type": "null" }, { "description": "The registered office, line by line.", "$ref": "#/components/schemas/Address" } ] }, "previousNames": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/PreviousName" }, "description": "Its former names, newest first." } }, "description": "A company's profile." }, "CompanyScreenRequest": { "type": "object", "properties": { "reference": { "type": [ "null", "string" ], "description": "The caller's own reference for the company, kept with the record." }, "disqualifications": { "type": "boolean", "description": "Whether to check each officer against Companies House's disqualified register too.", "default": false }, "watch": { "type": [ "null", "boolean" ], "description": "Whether to keep watching the company, its officers and its controllers, re-checked each time a list\n changes, as on /api/screen: for an account whose plan includes re-screening. Not given: as the plan says (not watched,\n unless it watches everything)." }, "watchMonths": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "For how long, 1 to 120 months; 12 if not given. Watching someone already watched renews it.", "format": "int32" }, "groupReference": { "type": [ "null", "string" ], "description": "The policy, quote or case it belongs to. Given, \"reference\" is the company's own reference; not given, \"reference\" is taken as the group's, as before." }, "monitor": { "type": [ "null", "boolean" ], "description": "The old name of watch: still taken for now, and going. Use watch.", "deprecated": true }, "monitorMonths": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The old name of watchMonths: still taken for now, and going. Use watchMonths.", "format": "int32", "deprecated": true } }, "description": "A company screening's options." }, "CompanySummary": { "required": [ "companyNumber", "name", "status", "type", "created", "address" ], "type": "object", "properties": { "companyNumber": { "type": "string" }, "name": { "type": "string" }, "status": { "type": [ "null", "string" ] }, "type": { "type": [ "null", "string" ] }, "created": { "type": [ "null", "string" ] }, "address": { "type": [ "null", "string" ] } }, "description": "A company found by a search." }, "Controller": { "required": [ "name", "kind", "companiesHouseKind", "birthYear", "birthMonth", "notifiedOn", "naturesOfControl" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "The name, as Companies House writes it; null where withheld." }, "kind": { "description": "Individual, corporate, legal person, or withheld.", "$ref": "#/components/schemas/ControllerKind" }, "companiesHouseKind": { "type": "string", "description": "Companies House's own word for it." }, "birthYear": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Year of birth, for an individual.", "format": "int32" }, "birthMonth": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Month of birth, for an individual.", "format": "int32" }, "notifiedOn": { "type": [ "null", "string" ], "description": "When notified." }, "naturesOfControl": { "type": "array", "items": { "type": "string" }, "description": "How they control it (\"ownership-of-shares-75-to-100-percent\")." }, "ceasedOn": { "type": [ "null", "string" ] }, "nationality": { "type": [ "null", "string" ] }, "countryOfResidence": { "type": [ "null", "string" ] }, "companyNumber": { "type": [ "null", "string" ] } }, "description": "A person with significant control, still notified." }, "ControllerKind": { "enum": [ "individual", "corporate", "legalPerson", "withheld" ], "type": "string", "description": "What a person with significant control is." }, "Decision": { "required": [ "decisionId", "subjectKey", "subjectName", "source", "listId", "entryCaption", "entryFingerprint", "verdict", "reason", "screeningId", "subjectId", "decidedBy", "decidedAt" ], "type": "object", "properties": { "decisionId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "subjectKey": { "type": "string" }, "subjectName": { "type": "string" }, "source": { "enum": [ "ca", "eu", "ofac", "ofac-cons", "uk", "un" ], "type": "string" }, "listId": { "type": "string" }, "entryCaption": { "type": [ "null", "string" ] }, "entryFingerprint": { "type": "string" }, "verdict": { "enum": [ "notThem", "isThem", "withdrawn" ], "type": "string" }, "reason": { "type": "string" }, "screeningId": { "type": "string", "format": "uuid" }, "subjectId": { "type": "string" }, "decidedBy": { "type": "string" }, "decidedAt": { "type": "string", "format": "date-time" } }, "description": "A decision recorded." }, "DecisionNote": { "required": [ "source", "listId", "verdict", "reason", "decidedBy", "decidedAt", "holds", "screeningId" ], "type": "object", "properties": { "source": { "enum": [ "ca", "eu", "ofac", "ofac-cons", "uk", "un" ], "type": "string" }, "listId": { "type": "string" }, "verdict": { "enum": [ "notThem", "isThem", "withdrawn" ], "type": "string" }, "reason": { "type": "string" }, "decidedBy": { "type": "string" }, "decidedAt": { "type": "string", "format": "date-time" }, "holds": { "type": "boolean" }, "screeningId": { "type": "string", "format": "uuid" } }, "description": "An earlier decision as a screening shows it: what was decided about which listed entry, by whom, when and why, and\nwhether it still holds (the entry is as it was when decided)." }, "DecisionRequest": { "required": [ "subjectId", "source", "listId", "verdict", "reason", "decidedBy" ], "type": "object", "properties": { "subjectId": { "type": [ "null", "string" ], "description": "The subject in the screening, as its answer named it (\"p1\", \"firm.officer2\")." }, "source": { "enum": [ "ca", "eu", "ofac", "ofac-cons", "uk", "un" ], "type": [ "null", "string" ], "description": "The list the entry is on: uk, eu, un, ca, ofac or ofac-cons." }, "listId": { "type": [ "null", "string" ], "description": "The entry's id on that list, as the match gave it." }, "verdict": { "enum": [ "notThem", "isThem", "withdrawn" ], "type": [ "null", "string" ], "description": "notThem, isThem or withdrawn." }, "reason": { "type": [ "null", "string" ], "description": "Why: kept with the decision, and shown whenever it's applied." }, "decidedBy": { "type": [ "null", "string" ], "description": "The person who decided." } }, "description": "A decision on a review, as a system records it." }, "Disqualification": { "required": [ "from", "until", "reason", "act", "underSanctions", "companies" ], "type": "object", "properties": { "from": { "type": [ "null", "string" ], "description": "From." }, "until": { "type": [ "null", "string" ], "description": "Until." }, "reason": { "type": [ "null", "string" ], "description": "Companies House's reason (\"disqualification-under-sanctions-regulation\")." }, "act": { "type": [ "null", "string" ], "description": "The act it's under." }, "underSanctions": { "type": "boolean", "description": "Whether it's a disqualification under sanctions regulations, which makes the officer a review at least." }, "companies": { "type": "array", "items": { "type": "string" }, "description": "The companies it names." } }, "description": "A disqualification on the register." }, "JsonElement": { }, "ListsAnswer": { "required": [ "ready", "parties", "lists" ], "type": "object", "properties": { "ready": { "type": "boolean", "description": "Whether the service may screen: every list loaded and current." }, "parties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "How many people, companies and ships the loaded lists hold between them.", "format": "int32" }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ListStatus" }, "description": "Each list's state." } }, "description": "What's loaded." }, "ListStatus": { "required": [ "source", "title", "loaded", "current", "generated", "downloadedAt", "checkedAt", "fingerprint", "parties" ], "type": "object", "properties": { "source": { "enum": [ "ca", "eu", "ofac", "ofac-cons", "uk", "un" ], "type": "string", "description": "The list's code." }, "title": { "type": "string", "description": "Its full name." }, "loaded": { "type": "boolean", "description": "Whether a version is loaded." }, "current": { "type": "boolean", "description": "Whether it was fetched successfully within the maximum age." }, "generated": { "type": [ "null", "string" ], "description": "When its publisher produced it, where known.", "format": "date-time" }, "downloadedAt": { "type": [ "null", "string" ], "description": "When the loaded version was first downloaded.", "format": "date-time" }, "checkedAt": { "type": [ "null", "string" ], "description": "When it was last fetched successfully.", "format": "date-time" }, "fingerprint": { "type": [ "null", "string" ], "description": "The loaded file's SHA-256." }, "parties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "How many parties it holds.", "format": "int32" } }, "description": "A list's state, as callers are told it." }, "NotScreened": { "required": [ "status", "title", "detail", "lists" ], "type": "object", "properties": { "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The HTTP status: 404 (no such company at Companies House), 502 (Companies House couldn't answer) or 503 (a list isn't current, the record couldn't be kept, or Companies House's rate limit is reached for now).", "format": "int32" }, "title": { "type": "string", "description": "\"Not screened\"." }, "detail": { "type": "string", "description": "Why, in a sentence." }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ListStatus" }, "description": "For 503, each list's state, so a stale one can be seen; otherwise empty." } }, "description": "The answer when nothing was screened: the status it came with, and why." }, "Officer": { "required": [ "name", "registeredName", "role", "isCorporate", "appointedOn", "birthYear", "birthMonth", "nationality", "occupation", "personNumber", "disqualifications" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name, written forenames first (\"Christopher Jon TAYLOR\")." }, "registeredName": { "type": "string", "description": "The name as Companies House writes it (\"TAYLOR, Christopher Jon\")." }, "role": { "type": "string", "description": "Director, secretary, LLP member..." }, "isCorporate": { "type": "boolean", "description": "Whether it's a company holding the office." }, "appointedOn": { "type": [ "null", "string" ], "description": "When appointed." }, "birthYear": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Year of birth, where shown.", "format": "int32" }, "birthMonth": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Month of birth, where shown.", "format": "int32" }, "nationality": { "type": [ "null", "string" ], "description": "Nationality, where shown." }, "occupation": { "type": [ "null", "string" ], "description": "Occupation, where shown." }, "personNumber": { "type": [ "null", "string" ], "description": "Companies House's number for the person, which links them to the disqualified register." }, "disqualifications": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/Disqualification" }, "description": "Disqualifications on the register; null when not checked." }, "officerId": { "type": [ "null", "string" ], "description": "Companies House's id for the person, from their appointments link: the same on every appointment\n they hold, where the person number may not be (Alison Beaton, secretary and director of AAB Farms Ltd)." }, "resignedOn": { "type": [ "null", "string" ] }, "countryOfResidence": { "type": [ "null", "string" ] }, "companyNumber": { "type": [ "null", "string" ] } }, "description": "An officer in office." }, "PartyMatch": { "required": [ "source", "listId", "caption", "matchedName", "score", "nameScore", "birthYearRuledOut", "regime" ], "type": "object", "properties": { "source": { "enum": [ "ca", "eu", "ofac", "ofac-cons", "uk", "un" ], "type": "string", "description": "The list the entry is on: uk, eu, un, ca, ofac or ofac-cons." }, "listId": { "type": "string", "description": "The list's own id for the entry, such as RUS0269 or EU.3633.76: give it back in a decision." }, "caption": { "type": "string", "description": "The entry's primary name, as the list gives it." }, "matchedName": { "type": "string", "description": "The entry's name (primary or alias) that scored best against the subject." }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "description": "The score, 0 to 1, after the birth year is taken into account; 1 is an exact match.", "format": "double" }, "nameScore": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "description": "The name's score alone, before the birth year.", "format": "double" }, "birthYearRuledOut": { "type": "boolean", "description": "Whether a birth year that doesn't fit cut the score." }, "regime": { "type": [ "null", "string" ], "description": "The sanctions regime it's listed under, where the list says." }, "entryFingerprint": { "type": [ "null", "string" ], "description": "The listed entry as it stands (ListedParty.Fingerprint): a decision about it holds while this does." } }, "description": "One listed party a subject resembles: what a review or a match is about." }, "PreviousName": { "required": [ "name", "from", "until" ], "type": "object", "properties": { "name": { "type": "string" }, "from": { "type": [ "null", "string" ] }, "until": { "type": [ "null", "string" ] } }, "description": "A name a company used to have." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "RecordedScreening": { "required": [ "screeningId", "screenedAt", "caller", "reference", "status", "subjectCount", "lists", "request", "result", "units", "verifyCode", "verifyUrl" ], "type": "object", "properties": { "screeningId": { "type": "string", "description": "The screening's id.", "format": "uuid" }, "screenedAt": { "type": "string", "description": "When it ran.", "format": "date-time" }, "caller": { "type": "string", "description": "The account it was recorded under." }, "reference": { "type": [ "null", "string" ], "description": "The group reference it was filed under, where there was one." }, "status": { "enum": [ "clear", "review", "match", "notScreened" ], "type": "string", "description": "clear, review, match or notScreened." }, "subjectCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "How many names were screened.", "format": "int32" }, "lists": { "description": "The lists as they stood, as recorded.", "$ref": "#/components/schemas/JsonElement" }, "request": { "description": "The request as made, as recorded.", "$ref": "#/components/schemas/JsonElement" }, "result": { "description": "The answer as given, as recorded: a ScreenAnswer's fields, less those added on the way out.", "$ref": "#/components/schemas/JsonElement" }, "units": { "description": "What the call billed.", "$ref": "#/components/schemas/CallUnits" }, "verifyCode": { "type": [ "null", "string" ], "description": "The record's verification code." }, "verifyUrl": { "type": [ "null", "string" ], "description": "The link that checks the record." } }, "description": "A screening as recorded: the lists, request and result are the JSON kept at the time." }, "RegisterAppointment": { "required": [ "type", "from", "until" ], "type": "object", "properties": { "type": { "type": "string" }, "from": { "type": [ "null", "string" ] }, "until": { "type": [ "null", "string" ] }, "naturesOfControl": { "type": [ "null", "array" ], "items": { "type": "string" } }, "companyNumber": { "type": [ "null", "string" ], "description": "On a person's own answer: the company it's in." }, "companyName": { "type": [ "null", "string" ] }, "companyStatus": { "type": [ "null", "string" ] } }, "description": "A role held: its type, from and until (null while current), and for an owner, the natures of control." }, "RegisterCompany": { "required": [ "companyNumber", "name", "status", "type", "created", "dissolved", "registeredOffice", "sicCodes", "previousNames" ], "type": "object", "properties": { "companyNumber": { "type": "string" }, "name": { "type": "string" }, "status": { "type": [ "null", "string" ] }, "type": { "type": [ "null", "string" ] }, "created": { "type": [ "null", "string" ] }, "dissolved": { "type": [ "null", "string" ] }, "registeredOffice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "sicCodes": { "type": "array", "items": { "type": "string" } }, "previousNames": { "type": "array", "items": { "$ref": "#/components/schemas/PreviousName" } } }, "description": "A company's own details." }, "RegisterCompanyAnswer": { "required": [ "company", "people", "withheld", "asOf" ], "type": "object", "properties": { "company": { "description": "The company.", "$ref": "#/components/schemas/RegisterCompany" }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterPerson" }, "description": "Everyone who holds or held a role in it, each once, with their appointments in it." }, "withheld": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Persons with significant control whose details Companies House withholds.", "format": "int32" }, "asOf": { "type": "string", "description": "When it was last confirmed with Companies House.", "format": "date-time" } }, "description": "A company as the register answers it." }, "RegisterPerson": { "required": [ "personId", "officerId", "kind", "name", "birthYear", "birthMonth", "nationality", "countryOfResidence", "occupation", "companyNumber", "appointments" ], "type": "object", "properties": { "personId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The register's ID.", "format": "int32" }, "officerId": { "type": [ "null", "string" ], "description": "Companies House's officer ID, where they're an officer." }, "kind": { "type": "string" }, "name": { "type": "string" }, "birthYear": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "birthMonth": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "nationality": { "type": [ "null", "string" ] }, "countryOfResidence": { "type": [ "null", "string" ] }, "occupation": { "type": [ "null", "string" ] }, "companyNumber": { "type": [ "null", "string" ], "description": "For a company holding a role, its own number, to look it up in turn." }, "appointments": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterAppointment" } }, "disqualifications": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/Disqualification" }, "description": "With ?disqualifications=true, their entries on the disqualified register." } }, "description": "Someone - a person, or a company - holding or having held roles." }, "ScreenAnswer": { "required": [ "units", "verifyCode", "verifyUrl" ], "type": "object", "properties": { "groupReference": { "type": [ "null", "string" ], "description": "The caller's reference for what this screening belongs to (a policy, quote or case); \"reference\" is its old name." }, "screeningId": { "type": "string", "description": "The screening's id, by which its record can be found.", "format": "uuid" }, "screenedAt": { "type": "string", "description": "When it ran.", "format": "date-time" }, "reference": { "type": [ "null", "string" ], "description": "The old name of groupReference: still taken and given for now, and going. Use groupReference.", "deprecated": true }, "status": { "enum": [ "clear", "review", "match" ], "type": "string", "description": "Match if any subject matched, else review if any is to be reviewed (or someone couldn't be screened), else clear." }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ListStatus" }, "description": "The version of each list screened against." }, "thresholds": { "description": "The thresholds in use.", "$ref": "#/components/schemas/ScreeningThresholds" }, "subjects": { "type": "array", "items": { "$ref": "#/components/schemas/SubjectAnswer" }, "description": "Each subject's result: those given, in order, each followed by those Companies House added for it." }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyLookup" }, "description": "What Companies House said about each company given by number." }, "unscreened": { "type": "array", "items": { "type": "string" }, "description": "Anyone who couldn't be screened, and why; any makes the screening a review at least." }, "watchedUntil": { "type": [ "null", "string" ], "description": "With \"monitor\": until when its subjects are watched, re-checked each time a list changes; null when not asked.", "format": "date-time" }, "units": { "description": "What the call billed.", "$ref": "#/components/schemas/CallUnits" }, "verifyCode": { "type": [ "null", "string" ], "description": "The record's verification code, for anyone given it to check the record at /verify." }, "verifyUrl": { "type": [ "null", "string" ], "description": "The link that checks the record." }, "notice": { "type": "string", "description": "What a result is and isn't, for any system that shows it to a person (decided 17 October 2026)." } }, "description": "A screening's answer, with what the call billed and how to verify the record." }, "ScreeningThresholds": { "type": "object", "properties": { "match": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double", "default": 0.9 }, "review": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double", "default": 0.7 } }, "description": "Where a score becomes a review or a match." }, "ScreenRequest": { "required": [ "subjects" ], "type": "object", "properties": { "reference": { "type": [ "null", "string" ], "description": "The old name of groupReference: still taken and given for now, and going. Use groupReference.", "deprecated": true }, "subjects": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/SubjectRequest" }, "description": "Who to screen." }, "disqualifications": { "type": "boolean", "description": "For a company given by number, whether to check each officer against Companies House's disqualified register too.", "default": false }, "watch": { "type": [ "null", "boolean" ], "description": "Whether to keep watching every subject screened, re-checked each time a list changes (Monitoring/): for an account whose\n plan includes re-screening. Not given: as the plan says (not watched, unless it watches everything)." }, "watchMonths": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "For how long, 1 to 120 months; 12 if not given. Watching someone already watched renews it.", "format": "int32" }, "lists": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Which lists to check, by source (\"uk\", \"eu\", \"un\", \"ca\", \"ofac\", \"ofac-cons\"); the UK's always. Not given: the account's choice, or every list." }, "groupReference": { "type": [ "null", "string" ], "description": "The caller's reference for what this screening belongs to: a policy, quote or case (decided 16 October 2026). Groups screenings across checks and time." }, "monitor": { "type": [ "null", "boolean" ], "description": "The old name of watch: still taken for now, and going. Use watch.", "deprecated": true }, "monitorMonths": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The old name of watchMonths: still taken for now, and going. Use watchMonths.", "format": "int32", "deprecated": true } }, "description": "A screening request." }, "ScreenResponse": { "required": [ "screeningId", "screenedAt", "status", "lists", "thresholds", "subjects", "companies", "unscreened" ], "type": "object", "properties": { "groupReference": { "type": [ "null", "string" ], "description": "The caller's reference for what this screening belongs to (a policy, quote or case); \"reference\" is its old name." }, "screeningId": { "type": "string", "description": "The screening's id, by which its record can be found.", "format": "uuid" }, "screenedAt": { "type": "string", "description": "When it ran.", "format": "date-time" }, "reference": { "type": [ "null", "string" ], "description": "The old name of groupReference: still taken and given for now, and going. Use groupReference.", "deprecated": true }, "status": { "enum": [ "clear", "review", "match" ], "type": "string", "description": "Match if any subject matched, else review if any is to be reviewed (or someone couldn't be screened), else clear." }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ListStatus" }, "description": "The version of each list screened against." }, "thresholds": { "description": "The thresholds in use.", "$ref": "#/components/schemas/ScreeningThresholds" }, "subjects": { "type": "array", "items": { "$ref": "#/components/schemas/SubjectAnswer" }, "description": "Each subject's result: those given, in order, each followed by those Companies House added for it." }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyLookup" }, "description": "What Companies House said about each company given by number." }, "unscreened": { "type": "array", "items": { "type": "string" }, "description": "Anyone who couldn't be screened, and why; any makes the screening a review at least." } }, "description": "A screening's answer." }, "SubjectAnswer": { "required": [ "subjectId", "name", "kind", "role", "companyNumber", "status", "score", "matchedName", "datasets", "matches" ], "type": "object", "properties": { "subjectId": { "type": "string", "description": "The subject's id, as given, or made for one Companies House added (\"firm.officer1\")." }, "name": { "type": "string", "description": "The name screened." }, "kind": { "description": "Person or company.", "$ref": "#/components/schemas/SubjectKind" }, "role": { "type": [ "null", "string" ], "description": "Their part: as given, or from Companies House (\"director\", \"person with significant control\")." }, "companyNumber": { "type": [ "null", "string" ], "description": "For one Companies House added, the company it came from." }, "status": { "enum": [ "clear", "review", "match" ], "type": "string", "description": "Clear, review or match." }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "description": "The best listed party's score.", "format": "double" }, "matchedName": { "type": [ "null", "string" ], "description": "The best party's matched name, where there is one." }, "datasets": { "type": "array", "items": { "enum": [ "ca", "eu", "ofac", "ofac-cons", "uk", "un" ], "type": "string" }, "description": "The lists the matches came from." }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/PartyMatch" }, "description": "The best few listed parties, best first." }, "disqualifications": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/Disqualification" }, "description": "For an officer, their disqualifications on Companies House's register; null when not checked." }, "birthYear": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The birth year screened with, where there was one.", "format": "int32" }, "birthMonth": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The birth month screened with, where there was one.", "format": "int32" }, "decisions": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/DecisionNote" }, "description": "The account's earlier decisions about the listed entries this subject resembled, which the status takes into account; null when there were none." }, "reference": { "type": [ "null", "string" ], "description": "The caller's own reference for this subject, as given; one Companies House added has its company's." }, "parentId": { "type": [ "null", "string" ], "description": "For one Companies House added, the subject it came with: the company's id." }, "register": { "oneOf": [ { "type": "null" }, { "description": "Its identity on Companies House's register, where it came from there.", "$ref": "#/components/schemas/SubjectRegister" } ] } }, "description": "One subject's result." }, "SubjectKind": { "enum": [ "person", "company" ], "type": "string", "description": "What a subject is." }, "SubjectRegister": { "type": "object", "properties": { "companyNumber": { "type": [ "null", "string" ] }, "officerId": { "type": [ "null", "string" ] }, "personId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } }, "description": "A subject's identity on Companies House's register, where it came from there (decided 16 October 2026): a company by its\nnumber; an officer by Companies House's officer ID, the same across all their appointments. A person with significant\ncontrol has none of their own unless they're also an officer." }, "SubjectRequest": { "required": [ "id", "kind" ], "type": "object", "properties": { "id": { "type": [ "null", "string" ], "description": "An id to answer by, unique in the request." }, "name": { "type": [ "null", "string" ], "description": "The name; for a company given by number, it may be left out and the registered name is used." }, "kind": { "oneOf": [ { "type": "null" }, { "description": "\"person\" or \"company\".", "$ref": "#/components/schemas/SubjectKind" } ] }, "birthYear": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "For a person, the year of birth where known.", "format": "int32" }, "birthMonth": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "For a person, the month of birth where known.", "format": "int32" }, "role": { "type": [ "null", "string" ], "description": "Their part (\"proposer\", \"principal\")." }, "companyNumber": { "type": [ "null", "string" ], "description": "For a company, its Companies House number: its officers and controllers are screened too." }, "of": { "type": [ "null", "string" ], "description": "For a person or company that came from a company - a watched officer, re-checked - that company's number, kept with\n them as it was, and not looked up again: not to be confused with CompanyNumber, which screens a company by its number." }, "reference": { "type": [ "null", "string" ], "description": "The caller's own reference for this person or company: a client or contact ID (decided 16 October 2026)." } }, "description": "One subject in a request." }, "ValidationProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "WatchItem": { "required": [ "watchId", "name", "kind", "birthYear", "birthMonth", "companyNumber", "role", "groupReference", "reference", "fromScreeningId", "startedAt", "endsAt", "endedAt", "live", "lastCheckedAt", "lastHitScreeningId" ], "type": "object", "properties": { "watchId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Its id, to end it by.", "format": "int64" }, "name": { "type": "string", "description": "The name watched, as screened." }, "kind": { "enum": [ "person", "company" ], "type": "string", "description": "person or company." }, "birthYear": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "As screened.", "format": "int32" }, "birthMonth": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "As screened.", "format": "int32" }, "companyNumber": { "type": [ "null", "string" ], "description": "For an officer or controller, the company they came from." }, "role": { "type": [ "null", "string" ], "description": "As screened." }, "groupReference": { "type": [ "null", "string" ], "description": "The policy, quote or case the screening was filed under." }, "reference": { "type": [ "null", "string" ], "description": "Your reference for the person or company, as screened." }, "fromScreeningId": { "type": "string", "description": "The screening that started or last renewed it.", "format": "uuid" }, "startedAt": { "type": "string", "description": "When it started.", "format": "date-time" }, "endsAt": { "type": "string", "description": "When it lapses unless renewed.", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "description": "When it was ended, if it was.", "format": "date-time" }, "live": { "type": "boolean", "description": "Whether it's running now." }, "lastCheckedAt": { "type": [ "null", "string" ], "description": "When it was last re-checked against a list's changes.", "format": "date-time" }, "lastHitScreeningId": { "type": [ "null", "string" ], "description": "The last re-check that found something: its screening.", "format": "uuid" } }, "description": "One watch." }, "WatchList": { "required": [ "live", "watches" ], "type": "object", "properties": { "live": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "How many are running now.", "format": "int32" }, "watches": { "type": "array", "items": { "$ref": "#/components/schemas/WatchItem" }, "description": "The watches asked for, newest first." } }, "description": "The account's watches." }, "WebhookAdded": { "required": [ "webhookId", "secret" ], "type": "object", "properties": { "webhookId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Its id.", "format": "int32" }, "secret": { "type": "string", "description": "Its signing secret (\"whsec_…\"), given this once: keep it with your system, to check each event's signature." } }, "description": "An address added." }, "WebhookDelivery": { "required": [ "deliveryId", "webhookId", "url", "eventId", "eventType", "createdAt", "attempts", "nextAttemptAt", "lastAttemptAt", "lastStatus", "lastError", "deliveredAt", "gaveUpAt" ], "type": "object", "properties": { "deliveryId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "webhookId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "url": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "attempts": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "nextAttemptAt": { "type": [ "null", "string" ], "format": "date-time" }, "lastAttemptAt": { "type": [ "null", "string" ], "format": "date-time" }, "lastStatus": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "lastError": { "type": [ "null", "string" ] }, "deliveredAt": { "type": [ "null", "string" ], "format": "date-time" }, "gaveUpAt": { "type": [ "null", "string" ], "format": "date-time" }, "state": { "type": [ "null", "string" ], "description": "delivered, waiting (to be tried again), or given up." } }, "description": "One event's delivery to one address." }, "WebhookEndpoint": { "required": [ "webhookId", "url", "events", "createdAt", "lastDeliveredAt", "waiting", "gaveUpThisWeek" ], "type": "object", "properties": { "webhookId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "lastDeliveredAt": { "type": [ "null", "string" ], "format": "date-time" }, "waiting": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "gaveUpThisWeek": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, "description": "An account's webhook address." }, "WebhookRequest": { "required": [ "url", "events" ], "type": "object", "properties": { "url": { "type": [ "null", "string" ], "description": "https, on the internet." }, "events": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "monitor.matched, decision.recorded; all of them if not given." } }, "description": "An address to add." } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "The caller's key, as issued on the account page: ssk_ and 43 characters.", "name": "X-Api-Key", "in": "header" } } }, "tags": [ { "name": "Lookup", "description": "Companies House: companies by name or number, a company with its directors and owners, a person with their roles. Free; nothing is screened or recorded. The company number a lookup gives is what makes a screening complete." }, { "name": "Screening", "description": "People and companies screened against the sanctions lists: by the names given, by a company's number (its directors and owners come with it), or from a company's name alone. Recorded, signed and billed at 3p a name." }, { "name": "Records", "description": "What was recorded: a screening by its id, and the decisions on its reviews." }, { "name": "Watches", "description": "Names watched for the account's re-screening plan: checked again whenever a list changes." }, { "name": "Webhooks", "description": "Addresses the service tells of re-check hits and decisions, and their deliveries." }, { "name": "Service", "description": "The lists' state, and whether the service may screen." } ], "externalDocs": { "description": "The API documentation, with examples in C#, VBA, curl, Python, PowerShell and JavaScript", "url": "https://policy365.ca/docs" }, "webhooks": { "monitor.matched": { "post": { "summary": "A watched name resembles a new or changed listed entry", "description": "A re-check, when a list changed, found someone you watch (POST /api/screen with watch) now resembling a listed entry; still a review or match after your decisions. Thin: ids and status, never the names screened; fetch the rest with your API key. Signed the Standard Webhooks way (standardwebhooks.com): check webhook-signature with your address's secret before trusting it. Answer any 2xx within 15 seconds; otherwise it's tried again after 1 minute, 5, 30, 2 hours, 6 and 12, then given up.", "parameters": [ { "name": "webhook-id", "in": "header", "description": "The event's id: the same on every try, so ignore one you've had.", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "description": "Seconds since 1970 when this try was signed: refuse one more than five minutes old.", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "description": "\"v1,\" then the base64 HMAC-SHA256 of \"{webhook-id}.{webhook-timestamp}.{body}\", keyed by your address's secret (the base64 after \"whsec_\").", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "id", "type", "time", "source", "data" ], "type": "object", "properties": { "id": { "type": "string", "description": "The event's id (\"evt_…\"), the same on every try: the webhook-id header." }, "type": { "type": "string", "description": "monitor.matched, decision.recorded or webhook.test." }, "time": { "type": "string", "description": "When it happened.", "format": "date-time" }, "source": { "type": "string", "description": "The service that sent it." }, "data": { "required": [ "screeningId", "watchId", "status", "groupReference", "reference", "list", "verifyUrl" ], "type": "object", "properties": { "screeningId": { "type": "string", "description": "The re-check's screening, a record of its own: GET /api/screenings/{id}.", "format": "uuid" }, "watchId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The watch: GET /api/monitor.", "format": "int64" }, "status": { "type": "string", "description": "review or match, after your decisions." }, "groupReference": { "type": [ "null", "string" ], "description": "The watch's group reference: the policy or case it was screened under." }, "reference": { "type": [ "null", "string" ], "description": "Your reference, as the watch has it." }, "list": { "required": [ "source", "generated", "fingerprint" ], "type": "object", "properties": { "source": { "type": "string", "description": "uk, eu, un, ca, ofac or ofac-cons." }, "generated": { "type": [ "null", "string" ], "description": "When the list says it was made.", "format": "date-time" }, "fingerprint": { "type": "string", "description": "The version's SHA-256, as the screenings' answers give it." } }, "description": "A list's version." }, "verifyUrl": { "type": [ "null", "string" ], "description": "Where the screening's record can be checked." } }, "description": "monitor.matched: a re-check found a watched name resembling a new or changed listed entry." } }, "description": "An event as sent: CloudEvents-shaped." } } }, "required": true }, "responses": { "2XX": { "description": "Received." } } } }, "decision.recorded": { "post": { "summary": "A decision was recorded", "description": "Someone on your account, or your system, decided whether a subject of a screening is a listed entry it resembled. Thin: ids and status, never the names screened; fetch the rest with your API key. Signed the Standard Webhooks way (standardwebhooks.com): check webhook-signature with your address's secret before trusting it. Answer any 2xx within 15 seconds; otherwise it's tried again after 1 minute, 5, 30, 2 hours, 6 and 12, then given up.", "parameters": [ { "name": "webhook-id", "in": "header", "description": "The event's id: the same on every try, so ignore one you've had.", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "description": "Seconds since 1970 when this try was signed: refuse one more than five minutes old.", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "description": "\"v1,\" then the base64 HMAC-SHA256 of \"{webhook-id}.{webhook-timestamp}.{body}\", keyed by your address's secret (the base64 after \"whsec_\").", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "id", "type", "time", "source", "data" ], "type": "object", "properties": { "id": { "type": "string", "description": "The event's id (\"evt_…\"), the same on every try: the webhook-id header." }, "type": { "type": "string", "description": "monitor.matched, decision.recorded or webhook.test." }, "time": { "type": "string", "description": "When it happened.", "format": "date-time" }, "source": { "type": "string", "description": "The service that sent it." }, "data": { "required": [ "decisionId", "screeningId", "subjectId", "source", "listId", "verdict", "decidedAt" ], "type": "object", "properties": { "decisionId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The decision.", "format": "int64" }, "screeningId": { "type": "string", "description": "The screening it's on: GET /api/screenings/{id}/decisions.", "format": "uuid" }, "subjectId": { "type": "string", "description": "The subject, as that screening's answer names it." }, "source": { "type": "string", "description": "The listed entry's list." }, "listId": { "type": "string", "description": "The listed entry." }, "verdict": { "type": "string", "description": "notThem, isThem or withdrawn." }, "decidedAt": { "type": "string", "description": "When.", "format": "date-time" } }, "description": "decision.recorded: someone decided whether a subject of a screening is a listed entry it resembled." } }, "description": "An event as sent: CloudEvents-shaped." } } }, "required": true }, "responses": { "2XX": { "description": "Received." } } } }, "webhook.test": { "post": { "summary": "A test", "description": "Sent on demand (Webhooks on the site, or POST /api/webhooks/{id}/test), to see an address works. Thin: ids and status, never the names screened; fetch the rest with your API key. Signed the Standard Webhooks way (standardwebhooks.com): check webhook-signature with your address's secret before trusting it. Answer any 2xx within 15 seconds; otherwise it's tried again after 1 minute, 5, 30, 2 hours, 6 and 12, then given up.", "parameters": [ { "name": "webhook-id", "in": "header", "description": "The event's id: the same on every try, so ignore one you've had.", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "description": "Seconds since 1970 when this try was signed: refuse one more than five minutes old.", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "description": "\"v1,\" then the base64 HMAC-SHA256 of \"{webhook-id}.{webhook-timestamp}.{body}\", keyed by your address's secret (the base64 after \"whsec_\").", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "id", "type", "time", "source", "data" ], "type": "object", "properties": { "id": { "type": "string", "description": "The event's id (\"evt_…\"), the same on every try: the webhook-id header." }, "type": { "type": "string", "description": "monitor.matched, decision.recorded or webhook.test." }, "time": { "type": "string", "description": "When it happened.", "format": "date-time" }, "source": { "type": "string", "description": "The service that sent it." }, "data": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string", "description": "Says it's a test." } }, "description": "webhook.test: sent on demand." } }, "description": "An event as sent: CloudEvents-shaped." } } }, "required": true }, "responses": { "2XX": { "description": "Received." } } } } } }