{ "openapi": "3.1.1", "info": { "title": "Sanctions Screening", "description": "Screens people and companies against the UK, EU, UN and Canadian sanctions lists. 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.", "version": "v1" }, "servers": [ { "url": "https://screening.policy365.cloud/" } ], "paths": { "/health": { "get": { "tags": [ "Sanctions.Service" ], "responses": { "200": { "description": "OK" } } } }, "/api/companies/check": { "post": { "tags": [ "Companies" ], "summary": "A company check from a name alone, for underwriting in the background. When exactly one active company has the\nname given (case, punctuation, \"The\", \"&\"/\"and\", Son/Sons, Brother/Brothers, Farm/Farms, spaced initials and the\nlegal form aside), it is screened with its officers\nand controllers: resolution \"matched\", status the screening's. Otherwise resolution \"ambiguous\" or \"notFound\",\nstatus \"notScreened\", and the candidates to choose from, each screened by /api/companies/{number}/screen.\nAlways 200 with an answer; 400, 502 and 503 only when something is wrong.", "requestBody": { "description": "Cancelled if the caller goes away.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCheckRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CompanyCheckRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CompanyCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CheckAnswer" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CheckAnswer" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CheckAnswer" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companies/check/csv": { "get": { "tags": [ "Companies" ], "summary": "The same check as POST /api/companies/check, 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.", "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": "monitor", "in": "query", "description": "When matched, whether to keep watching them; not given, as the account's plan says.", "schema": { "type": "boolean" } }, { "name": "monitorMonths", "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" } } ], "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/companies/search": { "get": { "tags": [ "Companies" ], "summary": "Companies matching a name or number, from Companies House. Looked up only: nothing is screened.", "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": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companies/{number}": { "get": { "tags": [ "Companies" ], "summary": "A company's profile, officers in office and persons with significant control, from Companies House. Looked up\nonly: nothing is screened.", "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" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CompanyLookup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookup" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CompanyLookup" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companies/{number}/screen": { "post": { "tags": [ "Companies" ], "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.", "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" } ] } }, "text/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompanyScreenRequest" } ] } }, "application/*+json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompanyScreenRequest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companies/{number}/screen/csv": { "get": { "tags": [ "Companies" ], "summary": "The same check as POST /api/companies/{number}/screen, 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.", "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": "monitor", "in": "query", "description": "Whether to keep watching them; not given, as the account's plan says.", "schema": { "type": "boolean" } }, { "name": "monitorMonths", "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" } } ], "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/monitor": { "get": { "tags": [ "Monitor" ], "summary": "The account's watches: those running now, or with all=true every one, ended and lapsed too. Newest first, at most 500.", "parameters": [ { "name": "all", "in": "query", "description": "Ended and lapsed watches too.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WatchList" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WatchList" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WatchList" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/monitor/{watchId}": { "delete": { "tags": [ "Monitor" ], "summary": "A watch ended: no more re-checks. 204, or 404 when it isn't one of the account's running watches.", "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" }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/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.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenRequest" }, "example": { "reference": "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" } ] } }, "text/json": { "schema": { "$ref": "#/components/schemas/ScreenRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ScreenRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ScreenAnswer" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "application/json": { "schema": { "$ref": "#/components/schemas/NotScreened" } }, "text/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.", "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" } } ], "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": [ "Screening" ], "summary": "A recorded screening: who asked, when, against which lists, the request and the answer.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RecordedScreening" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RecordedScreening" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RecordedScreening" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/screenings/{id}/decisions": { "post": { "tags": [ "Screening" ], "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/Decision" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Decision" } }, "text/json": { "schema": { "$ref": "#/components/schemas/Decision" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] }, "get": { "tags": [ "Screening" ], "summary": "The decisions recorded on a screening, oldest first.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/lists": { "get": { "tags": [ "Screening" ], "summary": "Each list's state, and whether the service may screen.", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ListsAnswer" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ListsAnswer" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ListsAnswer" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "The account's running addresses.", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "text/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.", "requestBody": { "description": "Cancelled if the caller goes away.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WebhookAdded" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAdded" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebhookAdded" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/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.", "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": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/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.", "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": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/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.", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "text/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.", "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": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } } }, "components": { "schemas": { "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 10p a unit." }, "CheckAnswer": { "required": [ "units", "verifyCode", "verifyUrl" ], "type": "object", "properties": { "resolution": { "description": "Matched, ambiguous or notFound.", "$ref": "#/components/schemas/CheckResolution" }, "status": { "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." } }, "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", "reference" ], "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 }, "monitor": { "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)." }, "monitorMonths": { "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" } }, "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" } } }, "description": "A company's profile." }, "CompanyScreenRequest": { "required": [ "reference" ], "type": "object", "properties": { "reference": { "type": [ "null", "string" ], "description": "The caller's own reference, kept with the record." }, "disqualifications": { "type": "boolean", "description": "Whether to check each officer against Companies House's disqualified register too.", "default": false }, "monitor": { "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)." }, "monitorMonths": { "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" } }, "description": "A company check'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\")." } }, "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": { "type": "string" }, "listId": { "type": "string" }, "entryCaption": { "type": [ "null", "string" ] }, "entryFingerprint": { "type": "string" }, "verdict": { "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": { "type": "string" }, "listId": { "type": "string" }, "verdict": { "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": { "type": [ "null", "string" ], "description": "The list the entry is on: uk, eu, un or ca." }, "listId": { "type": [ "null", "string" ], "description": "The entry's id on that list, as the match gave it." }, "verdict": { "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" }, "parties": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ListStatus" } } }, "description": "What's loaded." }, "ListStatus": { "required": [ "source", "title", "loaded", "current", "generated", "downloadedAt", "checkedAt", "fingerprint", "parties" ], "type": "object", "properties": { "source": { "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" ], "format": "int32" }, "title": { "type": "string" }, "detail": { "type": "string" }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ListStatus" } } }, "description": "The 503 answer: not screened, 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)." } }, "description": "An officer in office." }, "PartyMatch": { "required": [ "source", "listId", "caption", "matchedName", "score", "nameScore", "birthYearRuledOut", "regime" ], "type": "object", "properties": { "source": { "type": "string" }, "listId": { "type": "string" }, "caption": { "type": "string" }, "matchedName": { "type": "string" }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "nameScore": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "birthYearRuledOut": { "type": "boolean" }, "regime": { "type": [ "null", "string" ] }, "entryFingerprint": { "type": [ "null", "string" ] } } }, "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", "format": "uuid" }, "screenedAt": { "type": "string", "format": "date-time" }, "caller": { "type": "string" }, "reference": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "subjectCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "lists": { "$ref": "#/components/schemas/JsonElement" }, "request": { "$ref": "#/components/schemas/JsonElement" }, "result": { "$ref": "#/components/schemas/JsonElement" }, "units": { "$ref": "#/components/schemas/CallUnits" }, "verifyCode": { "type": [ "null", "string" ] }, "verifyUrl": { "type": [ "null", "string" ] } }, "description": "A screening as recorded: the lists, request and result are the JSON kept at the time." }, "ScreenAnswer": { "required": [ "units", "verifyCode", "verifyUrl" ], "type": "object", "properties": { "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 caller's own reference, as given, so the answer can be put with what asked for it." }, "status": { "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." } }, "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 } } }, "ScreenRequest": { "required": [ "reference", "subjects" ], "type": "object", "properties": { "reference": { "type": [ "null", "string" ], "description": "The caller's own reference (a quote or proposal number), kept with the record." }, "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 }, "monitor": { "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)." }, "monitorMonths": { "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" } }, "description": "A screening request." }, "ScreenResponse": { "required": [ "screeningId", "screenedAt", "reference", "status", "lists", "thresholds", "subjects", "companies", "unscreened" ], "type": "object", "properties": { "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 caller's own reference, as given, so the answer can be put with what asked for it." }, "status": { "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": { "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": { "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." } }, "description": "One subject's result." }, "SubjectKind": { "enum": [ "person", "company" ], "type": "string" }, "SubjectRequest": { "required": [ "id", "name", "kind", "birthYear", "birthMonth", "role" ], "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." } }, "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", "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": { "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." }, "reference": { "type": [ "null", "string" ], "description": "Your reference, 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 set under ApiKeys.", "name": "X-Api-Key", "in": "header" } } }, "tags": [ { "name": "Sanctions.Service" }, { "name": "Companies" }, { "name": "Monitor" }, { "name": "Screening" }, { "name": "Webhooks" } ], "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 monitor) 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", "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." }, "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 or ca." }, "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." } } } } } }