{ "openapi": "3.1.0", "info": { "title": "CCA Party Screening API", "version": "2.0.0", "description": "Profile-scoped party screening against authoritative sanctions, export-control, federal exclusion, and healthcare exclusion sources. A party may be an individual, organization, vessel, or aircraft. Potential matches require human review and retain each source-specific legal designation.\n\nThe service retains independent, immutable source artifacts and time-sequenced screening releases. Duplicate publisher artifacts enrich one designation, while cross-jurisdiction records are conservatively grouped only with official references, strong identifiers, or exact person name and date-of-birth evidence.\n\n## Cloudflare service binding\n\nCCA Workers should bind directly to `cca-party-screening-api` rather than call the public hostname:\n\n```json\n{\n \"services\": [\n {\n \"binding\": \"PARTY_SCREENING\",\n \"service\": \"cca-party-screening-api\"\n }\n ]\n}\n```\n\nThe default Worker entrypoint exposes `screen(input)`, `status(profiles)`, and `history(limit)`." }, "servers": [ { "url": "https://partyscreening.datasourceapi.com" } ], "x-cloudflare-service-binding": { "service": "cca-party-screening-api", "binding": "PARTY_SCREENING", "wrangler_jsonc": { "services": [ { "binding": "PARTY_SCREENING", "service": "cca-party-screening-api" } ] }, "http_example": "env.PARTY_SCREENING.fetch(new Request('https://partyscreening.internal/api/v2/screen', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input) }))", "rpc_example": "await env.PARTY_SCREENING.screen(input)" }, "paths": { "/api/v1/screen": { "post": { "deprecated": true, "operationId": "screenPartyLegacy", "summary": "Screen a party using the legacy flat response", "description": "Compatibility endpoint for Export Screening v1 clients. The legacy entityType input is mapped to partyType, and matches remain source-specific flat designations.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyScreeningInput" } } } }, "responses": { "200": { "description": "Completed legacy screening", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyScreeningEnvelope" } } } }, "400": { "description": "Invalid input" }, "503": { "description": "Required source coverage is missing, stale, or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyScreeningEnvelope" } } } } } } }, "/api/v2/screen": { "post": { "operationId": "screenParty", "summary": "Screen a party", "description": "Returns potential matches or fails closed with INCOMPLETE when required source coverage is unavailable.", "x-cloudflare-service-binding": { "http_path": "https://partyscreening.internal/api/v2/screen", "rpc_method": "screen" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningInput" } } } }, "responses": { "200": { "description": "Completed screening", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningEnvelope" } } } }, "400": { "description": "Invalid input" }, "503": { "description": "Required source coverage is missing, stale, or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningEnvelope" } } } } } } }, "/api/v1/status": { "get": { "operationId": "getStatus", "summary": "Get source readiness and freshness", "x-cloudflare-service-binding": { "http_path": "https://partyscreening.internal/api/v1/status", "rpc_method": "status" }, "responses": { "200": { "description": "All required sources are current" }, "503": { "description": "At least one required source is not ready" } } } }, "/api/v1/sources": { "get": { "operationId": "listSources", "summary": "List active source releases", "responses": { "200": { "description": "Public source inventory" } } } }, "/api/v1/history": { "get": { "operationId": "listReleaseHistory", "summary": "List screening and independent source-artifact releases", "description": "Returns time-sequenced screening index releases, immutable OFAC archive releases, and the latest artifact inventory with publisher and independently computed hashes.", "x-cloudflare-service-binding": { "http_path": "https://partyscreening.internal/api/v1/history", "rpc_method": "history" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Independent release and artifact history" } } } }, "/api/v1/history/{releaseId}": { "get": { "operationId": "getReleaseHistory", "summary": "Get one screening or artifact release", "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Release metadata and, for archive releases, its full artifact inventory" }, "404": { "description": "Release not found" } } } }, "/api/v1/history/{releaseId}/artifacts/{fileName}": { "get": { "operationId": "downloadArchivedArtifact", "summary": "Download an independently archived source artifact", "description": "Streams the immutable R2 copy and returns its independent SHA-256 in the X-Content-SHA256 response header.", "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete archived artifact" }, "206": { "description": "Requested byte range" }, "404": { "description": "Artifact or completed release not found" } } } } }, "components": { "schemas": { "ScreeningProfile": { "type": "string", "description": "Selects legal-context source groups. law_enforcement_notices contains wanted notices, which are not convictions or sanctions. procurement_debarments contains institution-specific contracting eligibility actions.", "enum": [ "sanctions", "export_controls", "federal_exclusions", "healthcare_exclusions", "law_enforcement_notices", "procurement_debarments" ] }, "CountryEvidence": { "type": "object", "required": [ "code", "basis", "value" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "basis": { "type": "string", "enum": [ "citizenship", "nationality", "vessel_flag", "place_of_birth", "address" ] }, "value": { "type": "string" } } }, "DesignationMatch": { "type": "object", "required": [ "sourceId", "releaseId", "entityId", "externalId", "primaryName", "sourceList", "publisher", "jurisdiction", "partyType", "profiles", "score", "evidence", "sourceRecord" ], "properties": { "sourceId": { "type": "string" }, "releaseId": { "type": "string" }, "entityId": { "type": "string" }, "externalId": { "type": "string" }, "primaryName": { "type": "string" }, "sourceList": { "type": "string" }, "publisher": { "type": "string" }, "jurisdiction": { "type": "string" }, "partyType": { "type": "string", "enum": [ "person", "organization", "vessel", "aircraft", "unknown", "other" ] }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/ScreeningProfile" } }, "programs": { "type": "array", "items": { "type": "string" } }, "addresses": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "countryEvidence": { "type": "array", "items": { "$ref": "#/components/schemas/CountryEvidence" } }, "datesOfBirth": { "type": "array", "items": { "type": "string" } }, "identifiers": { "type": "array", "items": { "type": "object" } }, "remarks": { "type": "string" }, "sourceListUrl": { "type": "string", "format": "uri" }, "sourceInformationUrl": { "type": "string", "format": "uri" }, "score": { "type": "number" }, "evidence": { "type": "object" }, "sourceRecord": { "type": "object", "description": "Complete normalized publisher evidence retained for this legal designation.", "additionalProperties": { "type": "string" } } } }, "LegacyDesignationMatch": { "type": "object", "required": [ "sourceId", "releaseId", "entityId", "entityType", "primaryName", "sourceList", "score", "evidence", "sourceRecord" ], "properties": { "sourceId": { "type": "string" }, "releaseId": { "type": "string" }, "entityId": { "type": "string" }, "entityType": { "type": "string", "enum": [ "person", "organization", "vessel", "aircraft", "unknown", "other" ] }, "primaryName": { "type": "string" }, "sourceList": { "type": "string" }, "programs": { "type": "array", "items": { "type": "string" } }, "addresses": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "countryEvidence": { "type": "array", "items": { "$ref": "#/components/schemas/CountryEvidence" } }, "datesOfBirth": { "type": "array", "items": { "type": "string" } }, "identifiers": { "type": "array", "items": { "type": "object" } }, "remarks": { "type": "string" }, "sourceListUrl": { "type": "string", "format": "uri" }, "sourceInformationUrl": { "type": "string", "format": "uri" }, "score": { "type": "number" }, "evidence": { "type": "object" }, "sourceRecord": { "type": "object", "additionalProperties": { "type": "string" } } } }, "PartyMatch": { "type": "object", "required": [ "partyId", "primaryName", "partyType", "names", "countries", "countryEvidence", "datesOfBirth", "identifiers", "profiles", "score", "evidence", "designations" ], "properties": { "partyId": { "type": "string" }, "primaryName": { "type": "string" }, "partyType": { "type": "string" }, "names": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "countryEvidence": { "type": "array", "items": { "$ref": "#/components/schemas/CountryEvidence" } }, "datesOfBirth": { "type": "array", "items": { "type": "string" } }, "identifiers": { "type": "array", "items": { "type": "object" } }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/ScreeningProfile" } }, "score": { "type": "number" }, "evidence": { "type": "object" }, "designations": { "type": "array", "items": { "$ref": "#/components/schemas/DesignationMatch" } } } }, "ScreeningInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "partyType": { "type": "string", "enum": [ "person", "organization", "vessel", "aircraft", "other" ] }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 code" }, "dateOfBirth": { "type": "string", "maxLength": 40 }, "identifiers": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "maxLength": 100 } } } }, "profiles": { "type": "array", "minItems": 1, "maxItems": 6, "uniqueItems": true, "default": [ "sanctions", "export_controls", "law_enforcement_notices" ], "items": { "$ref": "#/components/schemas/ScreeningProfile" } }, "threshold": { "type": "number", "minimum": 0.5, "maximum": 1, "default": 0.82 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "identifiers" ] } ] }, "LegacyScreeningInput": { "allOf": [ { "$ref": "#/components/schemas/ScreeningInput" }, { "type": "object", "properties": { "entityType": { "type": "string", "deprecated": true, "enum": [ "person", "organization", "vessel", "aircraft", "other" ] } } } ] }, "LegacyScreeningEnvelope": { "type": "object", "required": [ "request_status", "message", "data", "meta" ], "properties": { "request_status": { "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/LegacyScreeningResult" }, "meta": { "type": "object", "required": [ "request_id", "duration_ms" ], "properties": { "request_id": { "type": "string" }, "duration_ms": { "type": "number" } } } } }, "LegacyScreeningResult": { "type": "object", "required": [ "decision", "threshold", "scoreVersion", "matches", "sources", "freshness", "incompleteReasons", "screenedAt" ], "properties": { "decision": { "type": "string", "enum": [ "POTENTIAL_MATCH", "NO_MATCH", "INCOMPLETE" ] }, "threshold": { "type": "number" }, "scoreVersion": { "type": "string" }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyDesignationMatch" } }, "sources": { "type": "array", "items": { "type": "object" } }, "freshness": { "type": "object", "required": [ "ready", "requiredSourcesCurrent", "requiredSourcesExpected", "oldestVerifiedAt" ], "properties": { "ready": { "type": "boolean" }, "requiredSourcesCurrent": { "type": "integer" }, "requiredSourcesExpected": { "type": "integer" }, "oldestVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "incompleteReasons": { "type": "array", "items": { "type": "string" } }, "screenedAt": { "type": "string", "format": "date-time" } } }, "ScreeningEnvelope": { "type": "object", "required": [ "request_status", "message", "data", "meta" ], "properties": { "request_status": { "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ScreeningResult" }, "meta": { "type": "object", "required": [ "request_id", "duration_ms" ], "properties": { "request_id": { "type": "string" }, "duration_ms": { "type": "number" } } } } }, "ScreeningResult": { "type": "object", "required": [ "decision", "threshold", "scoreVersion", "profiles", "matches", "sources", "freshness", "incompleteReasons", "screenedAt" ], "properties": { "decision": { "type": "string", "enum": [ "POTENTIAL_MATCH", "NO_MATCH", "INCOMPLETE" ] }, "threshold": { "type": "number" }, "scoreVersion": { "type": "string" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/ScreeningProfile" } }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/PartyMatch" } }, "sources": { "type": "array", "items": { "type": "object" } }, "freshness": { "type": "object", "required": [ "ready", "requiredSourcesCurrent", "requiredSourcesExpected", "oldestVerifiedAt" ], "properties": { "ready": { "type": "boolean" }, "requiredSourcesCurrent": { "type": "integer" }, "requiredSourcesExpected": { "type": "integer" }, "oldestVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "incompleteReasons": { "type": "array", "items": { "type": "string" } }, "screenedAt": { "type": "string", "format": "date-time" } } } } } }