{ "openapi": "3.0.1", "info": { "version": "1.6.0", "title": "Diligent", "description": "Download Postman collection [here](https://docs.godiligent.ai/files/postman_collection.json).\n" }, "servers": [ { "url": "https://api.godiligent.ai", "description": "Production" }, { "url": "https://api.sandbox.godiligent.ai", "description": "Sandbox" } ], "security": [ { "xApiKey": [] } ], "tags": [ { "name": "CDD", "description": "Customer Due Diligence" }, { "name": "Company", "description": "Company Information" }, { "name": "Blocked Companies", "description": "Manage blocked companies" }, { "name": "Monitorings", "description": "Website monitoring and alerts for changes and risks" }, { "name": "Webhooks", "description": "\n## How to Secure Webhook Deliveries\nTo ensure that webhook payloads are securely transmitted and verified. This guide explains how to configure and validate\nwebhook deliveries using a shared secret.\n\n### How It Works\n\nWhen setting up a webhook, a secret is configured on both the sender (our system) and the receiver (your endpoint). Each\nwebhook payload is signed using this secret, allowing the receiver to verify its authenticity.\n\n#### Step 1: Configuring Your Webhook Secret\n\n1. When creating a webhook in our system, specify a unique secret key. This secret should be a strong, randomly\ngenerated string.\n2. Store this secret securely on your server; it should never be exposed publicly.\n\n#### Step 2: Receiving Webhook Payloads\n\nWhen your server receives a webhook event, the request will include an `X-Signature` header containing a HMAC signature\nof the payload.\n\nExample header:\n\n```\nX-Signature: sha256=abcdef1234567890...\n```\n\n#### Step 3: Validating the Webhook Signature\n\nTo verify the webhook payload:\n\n1. Retrieve the `X-Signature` value from the request headers.\n2. Compute the HMAC SHA-256 signature of the request payload using your webhook secret.\n3. Compare the computed signature with the one in the `X-Signature` header.\n4. If they match, the webhook is valid.\n\n#### (Python)\n\n```python\nimport hashlib\nimport hmac\nimport json\n\ndef verify_webhook_signature(secret, payload, signature):\n computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()\n expected_signature = f\"sha256={computed_signature}\"\n return hmac.compare_digest(expected_signature, signature)\n\n# Example usage:\nsecret = \"your_webhook_secret\"\npayload = json.dumps({\"event\": \"example\"})\nreceived_signature = \"sha256=abcdef1234567890...\"\n\nif verify_webhook_signature(secret, payload, received_signature):\n print(\"Valid webhook received!\")\nelse:\n print(\"Invalid webhook signature!\")\n```\n\n#### (JavaScript)\n\n```javascript\nconst crypto = require('crypto');\n\nfunction verifyWebhookSignature (secret, payload, signature) {\nconst computedSignature = `sha256=${crypto.createHmac('sha256', secret)\n.update(payload)\n.digest('hex')}`;\nreturn crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(signature));\n}\n\n// Example usage:\nconst secret = \"your_webhook_secret\";\nconst payload = JSON.stringify({ event: \"example\" });\nconst receivedSignature = \"sha256=abcdef1234567890...\";\n\nif (verifyWebhookSignature(secret, payload, receivedSignature)) {\nconsole.log(\"Valid webhook received!\");\n} else {\nconsole.log(\"Invalid webhook signature!\");\n}\n```\n\n#### Security Considerations\n\n- Always use HTTPS to prevent interception of webhook payloads.\n- Reject webhook requests that fail signature validation.\n- Rotate secrets periodically to enhance security.\n\nBy following this guide, you ensure that webhook deliveries are secure and trusted.\n" }, { "name": "Instant Screening (experimental)", "description": "Instant Website Screening API" } ], "paths": { "/cdds": { "post": { "tags": [ "CDD" ], "summary": "Perform CDD", "description": "Perform CDD on a given business. Supports idempotency to prevent duplicate processing of the same request.", "parameters": [ { "name": "idempotency-key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional idempotency key to ensure the same request is not processed multiple times. If the same key is sent with a different payload, a 409 Conflict error is returned. The result is cached for 7 days." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CDDRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CDDResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "409": { "description": "Conflict - Idempotency key already used with different payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict: Idempotency key already used with different payload" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] }, "get": { "tags": [ "CDD" ], "summary": "Get list of CDD", "description": "Get list of CDD", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Start date for filtering CDD cases (optional)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "End date for filtering CDD cases (optional)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "example": 1 }, "cases": { "type": "array", "items": { "$ref": "#/components/schemas/CDDShort" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/cdds/bulk": { "post": { "tags": [ "CDD" ], "summary": "Perform Bulk CDD", "description": "Perform CDD on multiple businesses", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CDDRequest" } } } }, "required": true }, "responses": { "200": { "description": "Bulk CDD operation completed", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CDDBulkResponseItem" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/cdds/{id}": { "get": { "tags": [ "CDD" ], "summary": "Get CDD by id", "description": "Get CDD results for a business", "parameters": [ { "name": "id", "in": "path", "description": "The id of the cdd request", "required": true, "schema": { "type": "string", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CDD" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/cdds/{id}/report": { "get": { "tags": [ "CDD" ], "summary": "Get CDD report by id", "description": "Get CDD report for a business", "parameters": [ { "name": "id", "in": "path", "description": "The id of the cdd request", "required": true, "schema": { "type": "string", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" } } ], "responses": { "200": { "description": "OK", "content": { "text/markdown": { "schema": { "type": "string", "format": "binary", "description": "The markdown content of the report" }, "example": "" } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/cdds/{id}/run-checks": { "post": { "tags": [ "CDD" ], "summary": "Run risk checks on a completed CDD case", "description": "Triggers risk checks on a completed CDD case. The case must be in COMPLETED state. Optionally accepts a risk check set ID to run specific checks.", "parameters": [ { "name": "id", "in": "path", "description": "The id of the cdd request", "required": true, "schema": { "type": "string", "format": "uuid", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "risk_check_set_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional risk check set ID to run specific checks. If not provided, the original risk check set ID used when case was created will be used.", "example": "a1b2c3d4-5678-90ab-cdef-1234567890ab" } } } } } }, "responses": { "200": { "description": "OK - Risk checks have been triggered successfully" }, "400": { "description": "Bad Request - Invalid case ID format or case is not in COMPLETED state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid case ID format" }, "errors": { "type": "array", "items": { "type": "object" } }, "message": { "type": "string", "example": "Case is not completed" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found - Case does not exist or does not belong to the customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Case not found" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "security": [ { "xApiKey": [] } ] } }, "/cdds/{id}/documents": { "post": { "tags": [ "CDD" ], "summary": "Add document to CDD", "description": "Add document to CDD", "parameters": [ { "name": "id", "in": "path", "description": "The id of the cdd request", "required": true, "schema": { "type": "string", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "type", "file" ], "properties": { "type": { "type": "string", "description": "The type of the document", "enum": [ "PROOF_OF_ADDRESS", "SHAREHOLDERS_LIST", "ARTICLES_OF_INCORPORATION" ], "example": "PROOF_OF_ADDRESS" }, "file": { "type": "string", "format": "binary", "description": "The file to upload" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/cdds/{id}/pull-registry-documents": { "post": { "tags": [ "CDD" ], "summary": "Pull registry documents", "description": "Pull registry documents", "parameters": [ { "name": "id", "in": "path", "description": "The id of the cdd request", "required": true, "schema": { "type": "string", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" } } ], "responses": { "204": { "description": "No Content - The request was successful and the documents are being processed." }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/cdds/{id}/customer-reviews": { "get": { "tags": [ "CDD" ], "summary": "List customer reviews by CDD id", "description": "List customer reviews for a given CDD case", "parameters": [ { "name": "id", "in": "path", "description": "The id of the cdd request", "required": true, "schema": { "type": "string", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "2c5edfb186c0b5939b5a5b1b1cd080a4" }, "business_id": { "type": "string", "example": "45_qjbmtm5v8Mk2GNyx3Vw" }, "provider": { "type": "string", "enum": [ "yelp", "bbb", "google_maps", "trustpilot", "facebook", "instagram" ], "example": "yelp" }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-28T03:13:27Z" }, "text": { "type": "string", "example": "Great craftsmanship and follow-through." }, "language": { "type": "string", "nullable": true, "example": "en" }, "rating": { "type": "integer", "example": 5 }, "user_name": { "type": "string", "example": "Melissa C." } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/blocked-companies": { "post": { "tags": [ "Company" ], "summary": "Block company", "description": "Block company by various data points", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CompanyBlockWebsite" }, { "$ref": "#/components/schemas/CompanyBlockLegalNameAddress" }, { "$ref": "#/components/schemas/CompanyBlockRegisterNumberAndCountryCode" } ] } } }, "required": true }, "responses": { "200": { "description": "Successfully blocked company, returns the created record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockedCompany" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } } }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } } }, "get": { "tags": [ "Company" ], "summary": "List blocked companies", "description": "Returns a list of all blocked companies. Optionally filter by customer_id.", "parameters": [ { "name": "register_number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by register_number" } ], "responses": { "200": { "description": "List of blocked companies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedCompany" } } } } }, "500": { "description": "Internal Server Error" } } } }, "/blocked-companies/{id}": { "delete": { "tags": [ "Company" ], "summary": "Unblock a company", "description": "Remove a company from the blocked list by its unique ID", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the blocked company record", "example": "bc-a91a8416-0a38" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found - Company block record doesn't exist" }, "500": { "description": "Internal Server Error" } } } }, "/monitoring-alerts": { "get": { "tags": [ "Monitorings" ], "summary": "List monitoring alerts", "description": "Retrieve a paginated list of monitoring alerts for the authenticated customer. Supports filtering by seen/unseen status and execution time, and provides an unseen alert count.", "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of alerts per page (1-100, default 10)" }, { "name": "next_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination token for next page (Base64-encoded)" }, { "name": "only_unacknowledged", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "If 'true', returns only unacknowledged alerts" }, { "name": "acknowledged", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "If 'true', returns only acknowledged alerts" }, { "name": "execution_time_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include alerts executed before this time (ISO8601)" }, { "name": "execution_time_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include alerts executed after this time (ISO8601)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringAlertsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/monitoring-alerts/acknowledge": { "post": { "tags": [ "Monitorings" ], "summary": "Acknowledge (mark as seen) monitoring alerts", "description": "Acknowledge (mark as seen) one or all monitoring alerts for the authenticated customer. Exactly one of alertId or all must be provided in the request body.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeAlertsRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeAlertsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Alert not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/companies/identify": { "get": { "tags": [ "Company" ], "summary": "identify", "description": "identify company by various data points", "parameters": [ { "name": "legal_name", "in": "query", "description": "The legal_name of the company", "required": false, "schema": { "type": "string", "example": "CrossLend GmbH" } }, { "name": "address", "in": "query", "description": "The address of the business, partial or full address", "required": false, "schema": { "type": "string", "example": "CrossLend GmbH" } }, { "name": "vat_number", "in": "query", "description": "The VAT number of the business", "required": false, "schema": { "type": "string", "example": "DE123456789" } }, { "name": "registry_profile", "in": "query", "description": "The level of details to be returned", "required": false, "schema": { "type": "string", "enum": [ "FULL", "BASIC" ], "example": "FULL" } }, { "name": "country_code", "in": "query", "description": "The country code of the business, in alpha-2 format (ISO 3166-1 alpha-2)", "required": false, "schema": { "type": "string", "example": "DE" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Registry" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/webhooks": { "post": { "summary": "Register or update webhook configuration", "operationId": "registerWebhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "Must be a valid URL starting with https." }, "is_active": { "type": "boolean", "default": true, "description": "Indicates if the webhook is active." }, "secret": { "type": "string", "description": "Secret key to sign the webhook payload, and will be passed in the `X-Signature` header." }, "events": { "type": "array", "description": "List of events to trigger the webhook. If not provided, no events will be triggered.", "items": { "type": "string", "enum": [ "cdd_state_changed", "monitoring_alert_fired" ], "description": "__cdd_state_changed__: When the state of a CDD changes to either inconclusive or complete. \n__monitoring_alert_fired__: When a monitoring alert is fired." } } }, "required": [ "webhook_url" ] } } } }, "responses": { "200": { "description": "Webhook configuration created or updated." }, "400": { "description": "Invalid input or validation error." } } }, "get": { "summary": "List registered webhooks", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "List of registered webhooks (limited to 1 for now).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID for the webhook." }, "webhook_url": { "type": "string", "format": "uri" }, "is_active": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "cdd_state_changed", "monitoring_alert_fired" ] } } } } } } } } } } }, "/webhooks/{webhook_id}/events": { "get": { "tags": [ "Webhooks" ], "summary": "List recent webhook deliveries", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "Webhook ID to filter deliveries.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of recent webhook delivery events.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "status_code": { "type": "integer", "example": 204 }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "payload": { "type": "object" } } }, "response": { "type": "object", "properties": { "headers": { "type": "object" }, "body": { "type": "object" } } } } } } } } } } } }, "/webhooks/{webhook_id}/events/{event_id}/redeliver": { "post": { "summary": "Redeliver a webhook event", "operationId": "redeliverWebhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "Webhook ID for the event to redeliver.", "schema": { "type": "string" } }, { "name": "event_id", "in": "path", "required": true, "description": "Event ID of the webhook to redeliver.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook redelivery initiated." }, "404": { "description": "Event or Webhook not found." }, "500": { "description": "Error during redelivery." } } } }, "/monitorings": { "post": { "tags": [ "Monitorings" ], "summary": "Create a new monitoring", "description": "Create a new monitoring for a customer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitoring" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] }, "get": { "tags": [ "Monitorings" ], "summary": "List monitorings", "description": "Get a list of monitorings for a customer", "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of items per page (1-100, default 10)" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "last_execution", "next_run", "state", "website" ], "default": "last_execution" }, "description": "Field to sort by (default: last_execution)" }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order (asc or desc, default desc)" }, { "name": "next_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination token for next page" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by running state" }, { "name": "website", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by specific website URL" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Monitoring" } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/monitorings/bulk-create": { "post": { "tags": [ "Monitorings" ], "summary": "Bulk create monitorings", "description": "Create multiple monitorings in a single request. All websites must be unique and not already exist for the customer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "allOf": [ { "$ref": "#/components/schemas/MonitoringRequest" }, { "type": "object", "properties": { "run_now": { "type": "boolean", "description": "If true, monitoring will be executed immediately after creation." }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional expiration date for the monitoring." } } } ] } } } } }, "responses": { "200": { "description": "Successful bulk creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_successful": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Monitoring" } } } } } } }, "400": { "description": "Validation or duplicate error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "website": { "type": "string", "description": "The duplicate website URL" }, "index": { "type": "integer", "description": "The index position of the duplicate item in the request array" } } }, "description": "List of duplicate website objects with their positions in the request array" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "xApiKey": [] } ] } }, "/monitorings/{id}/deactivate": { "delete": { "tags": [ "Monitorings" ], "summary": "Deactivate a monitoring", "description": "Deactivate a monitoring by ID", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "xApiKey": [] } ] } }, "/screen": { "post": { "summary": "Screen a website instantly for operational status (Experimental)", "tags": [ "Instant Screening (experimental)" ], "x-badges": [ { "name": "Beta", "position": "before", "color": "purple" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "website" ], "properties": { "website": { "type": "string", "format": "uri", "example": "https://example-store.com" } } } } } }, "responses": { "200": { "description": "Successful screening result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningResponse" } } } }, "400": { "description": "Invalid input" }, "500": { "description": "Server error" } } } } }, "components": { "schemas": { "MonitoringAlert": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert identifier", "example": "a1b2c3d4" }, "monitoring_id": { "type": "string", "format": "uuid", "description": "Monitoring ID", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" }, "customer_id": { "type": "string", "format": "uuid", "description": "Customer ID", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" }, "execution_result_id": { "type": "string", "format": "uuid", "description": "Execution result ID", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" }, "website": { "type": "string", "format": "uri", "description": "Website URL", "example": "https://example.com" }, "failed_checks": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string", "description": "Check type", "example": "non_operational_website" }, "explanation": { "type": "string", "description": "Explanation of the failed check", "example": "Website is not reachable" }, "method_used": { "type": "string", "description": "Method used to perform the check", "example": "AI" }, "status": { "type": "string", "description": "Status of the check", "example": "FAILED" } } }, "description": "Failed checks", "example": [{ "check": "non_operational_website", "explanation": "No Website Data found", "method_used": "", "status": "FAILED" }] }, "execution_time": { "type": "string", "description": "Execution time of the monitoring", "example": "2022-01-01T00:00:00.000Z" }, "created_at": { "type": "string", "description": "Creation time of the alert", "example": "2022-01-01T00:00:00.000Z" }, "acknowledged_at": { "type": "string", "nullable": true, "description": "Acknowledged time of the alert or null if not acknowledged", "example": "2025-08-01T06:12:47.905Z" }, "external_id": { "type": "string", "nullable": true, "description": "External reference ID or null if not set", "example": "123456" } } }, "MonitoringAlertsListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringAlert" } }, "unacknowledged_count": { "type": "integer", "description": "Number of unacknowledged alerts", "example": 1 }, "next_token": { "type": "string", "description": "Pagination token for next page (null if last page)", "example":"eyJjdXN0b21lcklkIjp7IlMiOiI2OWRmNWQ4MS0yYjc0LTRmNDItYTQwMS0xM2ViOTZiYTA2MTkifSwiZXhlY3V0aW9uVGltZSI6eyJTIjoiMjAyNS0wNy0zMVQxMjowMTozMC44OTFaIn19" } } }, "AcknowledgeAlertsRequest": { "type": "object", "properties": { "alert_id": { "type": "string", "description": "ID of the alert to acknowledge" }, "all": { "type": "boolean", "description": "If true, acknowledge all alerts" } }, "oneOf": [ { "required": [ "alert_id" ] }, { "required": [ "all" ] } ], "description": "Either alert_id OR all must be provided, but not both" }, "AcknowledgeAlertsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" }, "message": { "type": "string", "description": "Success message" }, "unacknowledged_count": { "type": "integer", "description": "Number of unacknowledged alerts remaining", "nullable": true } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } }, "CompanyInfo": { "type": "object", "properties": { "id": { "type": "string", "example": "XX_12345" }, "status": { "type": "string", "example": "active" }, "name": { "type": "string", "example": "CrossLend GmbH" }, "legal_form": { "type": "string", "example": "GmbH" }, "address": { "properties": { "country": { "type": "string", "example": "DE" }, "city": { "type": "string", "example": "Berlin" }, "state": { "type": "string", "example": "Berlin" }, "street": { "type": "string", "example": "Charlottenstraße 4" }, "postal_code": { "type": "string", "example": "10969" } } }, "register": { "properties": { "id": { "type": "string", "example": "HRB 12345 B" }, "city": { "type": "string", "example": "Charlottenburg (Berlin)" }, "country": { "type": "string", "example": "DE" }, "vat_number": { "type": "string", "example": "DE123456789" } } } } }, "ListMonitoringsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Monitoring" } }, "next_token": { "type": "string", "nullable": true } } }, "ExecutionResult": { "type": "object", "properties": { "executionTime": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "alerts": { "type": "array", "items": { "type": "object" } } } }, "MonitoringCreateItem": { "type": "object", "required": [ "website", "checks", "frequency" ], "properties": { "website": { "type": "string", "format": "uri" }, "checks": { "type": "array", "items": { "type": "string" } }, "frequency": { "type": "string", "enum": [ "weekly", "every_2_weeks", "every_3_weeks", "every_4_weeks" ] }, "expires_at": { "type": "string", "format": "date-time" }, "run_now": { "type": "boolean" }, "external_id": { "type": "string" } } }, "MonitoringBulkCreateRequest": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/MonitoringCreateItem" } }, "MonitoringBulkCreateResponse": { "type": "object", "properties": { "is_successful": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Monitoring" } }, "duplicates": { "type": "array", "items": { "type": "object" }, "nullable": true } } }, "CDDResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the CDD request", "example": "a91a8416-0a38-49e5-887e-8437519b3e78" }, "state": { "type": "string", "description": "The state of the CDD process", "enum": [ "INITIATED", "IN_PROGRESS", "RUNNING_CHECKS", "COMPLETED", "INCONCLUSIVE", "FAILED" ], "example": "INITIATED" }, "input": { "$ref": "#/components/schemas/CDDInput" }, "created_at": { "type": "string", "example": "2024-03-20T15:18:36.803Z", "format": "ISO8601" } } }, "CDDRequest": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CDDRequestWebsite" }, { "$ref": "#/components/schemas/CDDRequestLegalNameAddress" }, { "$ref": "#/components/schemas/CDDRequestRegisterNumberAndCountryCode" } ] }, "CDDRequestWebsite": { "type": "object", "required": [ "website" ], "properties": { "website": { "type": "string", "description": "The website of the business", "example": "example.com" }, "email": { "type": "string", "description": "The email of the business", "example": "fulan@domain.com" }, "legal_name": { "type": "string", "description": "The legal name of the business", "example": "PayLane Sp. z o.o." }, "address": { "type": "string", "description": "The address of the business", "example": "Am Generalshof 12, 10117 Berlin, Germany" }, "external_id": { "type": "string", "description": "Reference to be used in the customer's system", "example": "1538c2f9-ff0f-489e-0099-a5f116a4af07" }, "vat_number": { "type": "string", "description": "The VAT number of the business", "example": "BE09999999XX." }, "register_number": { "type": "string", "description": "The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported)", "example": "12345678" }, "country_code": { "type": "string", "description": "Country code in ISO 3166-1 alpha-2 format", "example": "DE" }, "description": { "type": "string", "description": "The description of the business", "example": "Software consultancy" }, "registry_profile": { "type": "string", "enum": [ "FULL", "BASIC" ] }, "contact_person": { "$ref": "#/components/schemas/ContactPerson" }, "risk_check_set_id": { "type": "string", "description": "The risk check set id, if not set the default risk check set will be used", "example": "550e8400-e29b-41d4-a716-446655440000" }, "pull_registry_documents": { "type": "boolean", "description": "Whether to pull registry documents for the company (Only supported for DE, and IT)", "default": false, "example": true }, "trading_name": { "type": "string", "description": "The trading name (DBA) of the business", "nullable": true, "example": "Acme Trading Co" }, "trading_address": { "type": "string", "description": "The trading address of the business", "nullable": true, "example": "123 Trade Street, London" } } }, "CDDBulkResponseItem": { "type": "object", "properties": { "index": { "type": "integer", "description": "Index of the input in the bulk request" }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Status of the processing for this item" }, "data": { "$ref": "#/components/schemas/CDDResponse" }, "message": { "type": "string", "description": "Error message if status is 'error'" } }, "required": [ "index", "status" ] }, "CDDBulkError": { "type": "object", "properties": { "index": { "type": "integer", "description": "Index of the input in the bulk request" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } }, "required": [ "index", "errors" ] }, "ValidationErrorItem": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" }, "description": "JSON path to the field with the error" }, "message": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code indicating the type of error" } }, "required": [ "path", "message", "code" ] }, "ValidationError": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } } }, "required": [ "errors" ] }, "BlockedCompany": { "type": "object", "required": [ "id", "reason", "blocked_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the blocked company record", "example": "bc-a91a8416-0a38" }, "website": { "type": "string", "description": "The website of the business (if provided)", "nullable": true, "example": "example.com" }, "email": { "type": "string", "description": "The email of the business (if provided)", "nullable": true, "example": "contact@example.com" }, "legal_name": { "type": "string", "description": "The legal name of the business (if provided)", "nullable": true, "example": "Example Company Ltd" }, "address": { "type": "string", "description": "The address of the business (if provided)", "nullable": true, "example": "123 Example Street, City" }, "country_code": { "type": "string", "description": "Country code in ISO 3166-1 alpha-2 format (if provided)", "nullable": true, "example": "DE" }, "vat_number": { "type": "string", "description": "The VAT number of the business (if provided)", "nullable": true, "example": "BE09999999XX" }, "register_number": { "type": "string", "description": "The registry number of the business (if provided)", "nullable": true, "example": "123456789" }, "reason": { "type": "string", "description": "The reason for blocking the company", "example": "Fraudulent activity" }, "notes": { "type": "string", "description": "Additional notes about the block", "nullable": true, "example": "Multiple reports of fraud from customers" }, "blocked_at": { "type": "string", "format": "date-time", "description": "When the company was blocked", "example": "2025-01-15T12:30:45Z" }, "external_id": { "type": "string", "description": "Reference ID from the customer's system (if provided)", "nullable": true, "example": "cust-12345" } } }, "CompanyBlockWebsite": { "type": "object", "required": [ "website", "reason" ], "properties": { "website": { "type": "string", "description": "The website of the business", "example": "example.com" }, "email": { "type": "string", "description": "The email of the business", "example": "fulan@domain.com" }, "legal_name": { "type": "string", "description": "The legal name of the business", "example": "PayLane ltd" }, "address": { "type": "string", "description": "The address of the business, or partial address", "example": "123 Imaginary St, 45678 Fictional City" }, "external_id": { "type": "string", "description": "Reference to be used in the customer's system", "example": "abc123 - my customer reference" }, "vat_number": { "type": "string", "description": "The VAT number of the business", "example": "BE09999999XX" }, "register_number": { "type": "string", "description": "The register number of the business", "example": "123546" }, "reason": { "type": "string", "description": "The reason for blocking the company", "example": "Fraudulent activity" }, "notes": { "type": "string", "description": "Additional notes for blocking the company", "example": "Company engaged in fraudulent activity" } } }, "CompanyBlockLegalNameAddress": { "type": "object", "required": [ "legal_name", "address", "reason" ], "properties": { "website": { "type": "string", "description": "The website of the business", "example": "example.com" }, "email": { "type": "string", "description": "The email of the business", "example": "fulan@domain.com" }, "legal_name": { "type": "string", "description": "The legal name of the business", "example": "PayLane ltd" }, "address": { "type": "string", "description": "The address of the business, or partial address", "example": "123 Imaginary St, 45678 Fictional City" }, "external_id": { "type": "string", "description": "Reference to be used in the customer's system", "example": "abc123 - my customer reference" }, "vat_number": { "type": "string", "description": "The VAT number of the business", "example": "BE09999999XX" }, "register_number": { "type": "string", "description": "The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported)", "example": "12345678" }, "reason": { "type": "string", "description": "The reason for blocking the company", "example": "Fraudulent activity" }, "notes": { "type": "string", "description": "Additional notes for blocking the company", "example": "Company engaged in fraudulent activity" } } }, "CompanyBlockRegisterNumberAndCountryCode": { "type": "object", "required": [ "register_number", "country_code" ], "properties": { "website": { "type": "string", "description": "The website of the business", "example": "example.com" }, "email": { "type": "string", "description": "The email of the business", "example": "fulan@domain.com" }, "legal_name": { "type": "string", "description": "The legal name of the business", "example": "PayLane ltd" }, "address": { "type": "string", "description": "The address of the business, or partial address", "example": "123 Imaginary St, 45678 Fictional City" }, "external_id": { "type": "string", "description": "Reference to be used in the customer's system", "example": "abc123 - my customer reference" }, "vat_number": { "type": "string", "description": "The VAT number of the business", "example": "BE09999999XX" }, "register_number": { "type": "string", "description": "The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported)", "example": "12345678" }, "reason": { "type": "string", "description": "The reason for blocking the company", "example": "Fraudulent activity" }, "notes": { "type": "string", "description": "Additional notes for blocking the company", "example": "Company engaged in fraudulent activity" } } }, "CDDRequestLegalNameAddress": { "type": "object", "required": [ "legal_name", "address" ], "properties": { "website": { "type": "string", "description": "The website of the business", "example": "example.com" }, "email": { "type": "string", "description": "The email of the business", "example": "fulan@domain.com" }, "legal_name": { "type": "string", "description": "The legal name of the business", "example": "PayLane Sp. z o.o." }, "address": { "type": "string", "description": "The address of the business", "example": "Am Generalshof 12, 10117 Berlin, Germany" }, "external_id": { "type": "string", "description": "Reference to be used in the customer's system", "example": "1538c2f9-ff0f-489e-0099-a5f116a4af07" }, "vat_number": { "type": "string", "description": "The VAT number of the business", "example": "BE09999999XX." }, "register_number": { "type": "string", "description": "The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported)", "example": "12345678" }, "country_code": { "type": "string", "description": "Country code in ISO 3166-1 alpha-2 format", "example": "DE" }, "description": { "type": "string", "description": "The description of the business", "example": "Software consultancy" }, "registry_profile": { "type": "string", "enum": [ "FULL", "BASIC" ] }, "contact_person": { "$ref": "#/components/schemas/ContactPerson" }, "risk_check_set_id": { "type": "string", "description": "The risk check set id, if not set the default risk check set will be used", "example": "550e8400-e29b-41d4-a716-446655440000" }, "pull_registry_documents": { "type": "boolean", "description": "Whether to pull registry documents for the company (Only supported for DE, and IT)", "default": false, "example": true }, "trading_name": { "type": "string", "description": "The trading name (DBA) of the business", "nullable": true, "example": "Acme Trading Co" }, "trading_address": { "type": "string", "description": "The trading address of the business", "nullable": true, "example": "123 Trade Street, London" } } }, "CDDRequestRegisterNumberAndCountryCode": { "type": "object", "required": [ "register_number", "country_code" ], "properties": { "website": { "type": "string", "description": "The website of the business", "example": "example.com" }, "email": { "type": "string", "description": "The email of the business", "example": "fulan@domain.com" }, "legal_name": { "type": "string", "description": "The legal name of the business", "example": "PayLane Sp. z o.o." }, "address": { "type": "string", "description": "The address of the business", "example": "Am Generalshof 12, 10117 Berlin, Germany" }, "external_id": { "type": "string", "description": "Reference to be used in the customer's system", "example": "1538c2f9-ff0f-489e-0099-a5f116a4af07" }, "vat_number": { "type": "string", "description": "The VAT number of the business", "example": "BE09999999XX." }, "register_number": { "type": "string", "description": "The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported)", "example": "12345678" }, "country_code": { "type": "string", "description": "Country code in ISO 3166-1 alpha-2 format", "example": "DE" }, "description": { "type": "string", "description": "The description of the business", "example": "Software consultancy" }, "registry_profile": { "type": "string", "enum": [ "FULL", "BASIC" ] }, "contact_person": { "$ref": "#/components/schemas/ContactPerson" }, "risk_check_set_id": { "type": "string", "description": "The risk check set id, if not set the default risk check set will be used", "example": "550e8400-e29b-41d4-a716-446655440000" }, "pull_registry_documents": { "type": "boolean", "description": "Whether to pull registry documents for the company (Only supported for DE, and IT)", "default": false, "example": true }, "trading_name": { "type": "string", "description": "The trading name (DBA) of the business", "nullable": true, "example": "Acme Trading Co" }, "trading_address": { "type": "string", "description": "The trading address of the business", "nullable": true, "example": "123 Trade Street, London" } } }, "Report": { "type": "object", "properties": { "id": { "type": "string", "example": "1538c2f9-ff0f-489e-0099-a5f116a4af07" }, "content_type": { "type": "string", "example": "text/markdown" }, "content": { "type": "string", "example": "## Report" }, "created_at": { "type": "string", "format": "ISO8601", "example": "2023-04-30T23:50:51.222Z" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the document", "example": "doc_123" }, "created_at": { "type": "string", "format": "ISO8601", "description": "The date the document was created", "example": "2023-04-30T23:50:51.222Z" }, "file_name": { "type": "string", "description": "The name of the document", "example": "proof_of_address.pdf" }, "file_type": { "type": "string", "description": "mime type of the file", "enum": [ "application/pdf" ], "example": "application/pdf" }, "type": { "type": "string", "description": "The type of the document", "enum": [ "CHRONOLOGICAL_EXTRACT", "SHAREHOLDER_LIST", "REGISTRY_EXCERPT", "INCORPORATION", "OWNERSHIP_AND_SHAREHOLDING_CHANGES", "OFFICER_CHANGES", "FINANCIAL_STATEMENTS", "ADDRESS_AND_STRUCTURAL_CHANGES" ], "example": "INCORPORATION" }, "url": { "type": "string", "description": "The URL to download the document", "example": "https://example-bucket.s3.eu-central-1.amazonaws.com/placeholder-folder/sample-document.pdf" } } }, "SslInfo": { "type": "object", "properties": { "is_valid": { "type": "boolean", "example": false }, "valid_from": { "type": "string", "example": "2023-02-25T11:45:11.000Z", "format": "ISO8601" }, "valid_to": { "type": "string", "example": "2024-03-28T11:45:10.000Z", "format": "ISO8601" }, "days_until_expiration": { "type": "integer", "example": 147 }, "valid_for": { "type": "array", "items": { "type": "string", "example": "webflow.io" } } } }, "DomainInformation": { "type": "object", "properties": { "name": { "type": "string", "example": "spyra.com" }, "ssl": { "$ref": "#/components/schemas/SslInfo" }, "extension": { "type": "string", "example": "com" }, "ips_v4": { "type": "array", "items": { "type": "string", "example": "129.0.0.1" } }, "is_disposable": { "type": "boolean", "example": false }, "status": { "type": "array", "items": { "type": "string", "example": "clientdeleteprohibited" } }, "registrar": { "type": "string", "example": "GoDaddy.com, LLC" }, "registrant": { "type": "string", "example": "Spyra GmbH" }, "created_at": { "type": "string", "example": "2000-02-06T18:03:12Z", "format": "ISO8601" }, "expires_at": { "type": "string", "format": "ISO8601", "example": "2025-08-18T11:59:59Z" }, "age": { "type": "integer", "example": 8670 }, "country": { "type": "string", "example": "US" }, "isp_name": { "type": "string", "example": "Fastly Inc." } } }, "Source": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "example": "Source Name" }, "link": { "type": "string", "example": "https://www.example.com" } } }, "CDDShort": { "type": "object", "properties": { "id": { "type": "string", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" }, "state": { "type": "string", "enum": [ "INITIATED", "COMPLETED", "FAILED" ], "example": "COMPLETED" }, "input": { "$ref": "#/components/schemas/CDDInput" }, "created_at": { "type": "string", "format": "ISO8601", "example": "2024-03-20T15:18:36.803Z" }, "checks": { "type": "object", "properties": { "verdict": { "type": "string", "description": "The final verdict of the CDD", "enum": [ "ACCEPT", "REVIEW", "REJECT" ], "example": "ACCEPT" }, "groups": { "type": "array", "description": "The groups of checks configured by the user", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the group", "example": "onboarding" }, "action": { "type": "string", "description": "The action to take if the group fails", "enum": [ "ACCEPT", "REVIEW", "REJECT" ], "example": "ACCEPT" } } } } } } } }, "CDDInput": { "type": "object", "description": "What was used to perform the CDD", "properties": { "website": { "type": "string", "description": "The website of the business", "example": "https://example.com" }, "email": { "type": "string", "description": "The email of the business", "example": "fulan@domain.com" }, "legal_name": { "type": "string", "description": "The legal name of the business", "example": "PayLane Sp. z o.o." }, "registry_profile": { "type": "string", "enum": [ "FULL", "BASIC" ] }, "address": { "type": "string", "description": "The address of the business", "example": "Am Generalshof 12, 10117 Berlin, Germany" }, "external_id": { "type": "string", "description": "Reference to be used in the customer's system", "example": "1538c2f9-ff0f-489e-0099-a5f116a4af07" }, "vat_number": { "type": "string", "description": "The VAT number of the business", "example": "BE09999999XX." } } }, "CDD": { "type": "object", "description": "The CDD case details", "required": [ "id", "state", "input" ], "properties": { "id": { "type": "string", "description": "The id of the CDD request", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" }, "state": { "type": "string", "description": "The state of the CDD", "example": "COMPLETED" }, "input": { "$ref": "#/components/schemas/CDDInput" }, "created_at": { "type": "string", "format": "ISO8601", "example": "2024-03-20T15:18:36.803Z" }, "online_screening": { "$ref": "#/components/schemas/OnlineScreening" }, "registry": { "$ref": "#/components/schemas/Registry" }, "documents": { "type": "array", "description": "The documents uploaded or collected for the CDD case", "items": { "$ref": "#/components/schemas/Document" } }, "checks": { "$ref": "#/components/schemas/Checks" } } }, "Registry": { "type": "object", "required": [ "name", "legal_form", "register", "address", "ownership", "source" ], "properties": { "status": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "REGISTERED", "INACTIVE", "SUSPENDED", "IN_REGISTRATION", "TERMINATED" ] }, "name": { "type": "string", "example": "XYZZ GmbH" }, "commercial_name": { "type": "string" }, "is_blocked": { "type": "boolean", "default": false }, "legal_form": { "type": "string", "example": "GmbH" }, "description": { "type": "string", "example": "SOFTWARE CONSULTANCY" }, "register": { "type": "object", "required": [ "id", "country" ], "properties": { "id": { "type": "string", "example": "HRB 259538 B" }, "country": { "type": "string", "example": "DE" }, "city": { "type": "string", "example": "Charlottenburg (Berlin)" }, "foundation_date": { "type": "string", "example": "2023-12-04" } } }, "address": { "$ref": "#/components/schemas/Address" }, "vat_number": { "type": "string" }, "representation_rules": { "type": "string", "example": "This is a placeholder for representation rules." }, "signatory_powers": { "type": "array", "items": { "$ref": "#/components/schemas/SignatoryPower" } }, "ownership": { "type": "object", "properties": { "shareholders": { "type": "array", "items": { "$ref": "#/components/schemas/Shareholder" } }, "total_percentage": { "type": "integer", "example": 100 }, "total_shareholders_count": { "type": "integer", "example": 1 }, "total_major_shareholders_count": { "type": "integer", "example": 1 }, "total_ubos_count": { "type": "integer", "example": 1 } } }, "industry_classifications": { "type": "object", "properties": { "ateco": { "type": "array", "items": { "type": "string", "example": "47199" } }, "nace": { "type": "array", "items": { "type": "string", "example": "4719" } }, "sic": { "type": "array", "items": { "type": "string", "example": "5999" } } } }, "pec": { "type": "string", "example": "QUADERNOAQUADRETTISRL@ARUBAPEC.IT" }, "rea_code": { "type": "string", "example": "128207" }, "financials": { "type": "object", "properties": { "date": { "type": "string", "example": "2022-12-31" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "share_capital", "enum": [ "turnover", "share_capital", "net_worth" ] }, "note": { "type": "string", "description": "The note of the financial item" }, "unit": { "type": "string", "example": "EUR" }, "value": { "type": "number", "format": "int64", "example": 100000 } } } } } }, "extras": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "website" }, "value": { "type": "string", "example": "www.example.eu" } } } }, "source": { "$ref": "#/components/schemas/Source" } } }, "OnlineScreening": { "type": "object", "description": "Data from online presence of the business", "properties": { "legal_name": { "type": "string", "example": "PayLane Sp. z o.o." }, "names": { "type": "array", "items": { "$ref": "#/components/schemas/Name" } }, "industry": { "$ref": "#/components/schemas/Industry" }, "addresses": { "$ref": "#/components/schemas/Addresses" }, "websites": { "$ref": "#/components/schemas/Websites" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "identification_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/IdentificationNumber" } } } }, "Checks": { "type": "object", "description": "The checks performed on the business", "properties": { "verdict": { "type": "string", "enum": [ "ACCEPT", "REVIEW", "REJECT" ], "example": "ACCEPT" }, "groups": { "type": "array", "description": "The groups of checks configured by the user", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "onboarding" }, "description": { "type": "string", "example": "Onboarding checks" }, "type": { "type": "string", "enum": [ "BINARY", "SCORE" ], "example": "BINARY" }, "result": { "type": "boolean", "description": "Whether the group passed or not", "example": true }, "score": { "type": "integer", "description": "only applicable if type is SCORE", "example": 0 }, "action": { "type": "string", "enum": [ "ACCEPT", "REVIEW", "REJECT" ], "example": "ACCEPT" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/Check" } } } } } } }, "Check": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the check", "example": "is_online_seller" }, "description": { "type": "string", "description": "The description of the check", "example": "Checks if a website is an online shop i.e. ecommerce (excluding tourism and travel websites)" }, "result": { "type": "boolean", "description": "The result of the check, true indicates positive outcome, false indicates negative outcome, null indicates the check was not performed due to missing data", "enum": [ true, false, null ], "example": true }, "score": { "type": "integer", "description": "only applicable if type of associated group is SCORE", "example": 0 }, "context": { "type": "string", "description": "The context of the check", "example": "website" }, "meta": { "type": "object", "description": "unstructured data related to the check", "additionalProperties": true } } }, "Industry": { "type": "object", "properties": { "is_online_seller": { "type": "boolean", "example": true }, "one_liner": { "type": "object", "properties": { "text": { "type": "string", "example": "Billie is a B2B platform offering 'Buy Now, Pay Later' solutions to enhance checkout experiences and boost sales." } } }, "summary": { "type": "object", "properties": { "text": { "type": "string", "example": "Billie.io is a German-based financial technology company that offers a \"Buy Now, Pay Later\" (BNPL) payment platform specifically designed for B2B transactions. The company enables online merchants to increase sales by providing their business customers with flexible payment options and terms, ranging from 14 to 120 days. Merchants receive immediate payouts while Billie assumes the risk. The platform boasts high acceptance rates and aims to improve customer satisfaction and checkout conversion rates. Billie's services include real-time customer verification, professional dunning processes, and automatic payment allocation. The company generates revenue by facilitating these transactions and providing additional financial services to B2B merchants." } } }, "risk_categories": { "type": "array", "items": { "$ref": "#/components/schemas/RiskCategory" } }, "schemes": { "$ref": "#/components/schemas/IndustrySchemes" } } }, "RiskCategory": { "type": "object", "properties": { "description": { "type": "string", "example": "Business is not operating in a prohibited industry." }, "category": { "type": "string", "example": "OTHER_NON_PROHIBITED" }, "is_high_risk": { "type": "boolean", "example": false }, "explanation": { "type": "string" } } }, "IndustrySchemes": { "type": "object", "properties": { "naics": { "$ref": "#/components/schemas/IndustryScheme" }, "sic": { "$ref": "#/components/schemas/IndustryScheme" }, "nace": { "$ref": "#/components/schemas/IndustryScheme" }, "mcc": { "$ref": "#/components/schemas/IndustryScheme" } } }, "IndustryScheme": { "type": "object", "properties": { "primary": { "$ref": "#/components/schemas/IndustrySchemeItem" }, "additional": { "type": "array", "items": { "$ref": "#/components/schemas/IndustrySchemeItem" } } } }, "SignatoryPower": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "date_of_birth": { "type": "string", "example": "1990-01-01" }, "entity_name": { "type": "string", "example": "Example GmbH" }, "location": { "type": "string", "example": "City, Country" }, "role": { "type": "string", "example": "ROLE" }, "effective_date": { "type": "string", "example": "2024-01-01" }, "representation": { "type": "string", "example": "Representation details" }, "role_local": { "type": "string", "example": "Role" }, "signatory_power": { "type": "string", "example": "POWER_TYPE" } } }, "Shareholder": { "type": "object", "properties": { "name": { "type": "string", "example": "John Doe" }, "percentage": { "type": "integer", "example": 100 }, "type": { "type": "string", "example": "INDIVIDUAL" }, "location": { "type": "string", "example": "City, Country" }, "is_major_shareholder": { "type": "boolean", "example": true }, "is_ubo": { "type": "boolean", "example": true }, "gender": { "type": "string", "example": "MALE" }, "tax_code": { "type": "string", "example": "123456789" }, "address": { "type": "string", "example": "123 Main St, City, Country" } } }, "IndustrySchemeItem": { "type": "object", "properties": { "code": { "type": "string", "example": "6499" }, "description": { "type": "string", "example": "649 Other financial service activities, except insurance and pension funding activities" }, "source": { "type": "string", "example": "paylane" }, "explanation": { "type": "string", "example": "The primary NAICS code 522320 is applicable due to the company's core business of facilitating financial transactions and providing a payment platform for B2B transactions." } } }, "Addresses": { "type": "object", "properties": { "primary": { "$ref": "#/components/schemas/Address" }, "additional": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } }, "Address": { "type": "object", "properties": { "formatted_address": { "type": "string", "example": "123 Imaginary St, 45678 Fictional City" }, "components": { "type": "object", "properties": { "street": { "type": "string", "example": "Imaginary St" }, "street_number": { "type": "string", "example": "123" }, "state": { "type": "string", "example": "IS" }, "locality_code": { "type": "string", "example": "IS" }, "city": { "type": "string", "example": "Fictional City" }, "postal_code": { "type": "string", "example": "45678" }, "country_code": { "type": "string", "example": "FC" }, "country": { "type": "string", "example": "Fictionland" } } }, "type": { "type": "string", "enum": [ "residential", "business", "unknown" ], "example": "residential" }, "is_valid": { "type": "boolean", "example": true }, "is_verified": { "type": "boolean", "example": true }, "is_suspicious": { "type": "boolean", "example": false }, "is_blacklisted": { "type": "boolean", "example": false }, "is_primary": { "type": "boolean", "example": true }, "street_view": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Websites": { "type": "object", "properties": { "primary": { "$ref": "#/components/schemas/Website" }, "additional": { "type": "array", "items": { "$ref": "#/components/schemas/AdditionalWebsite" } } } }, "AdditionalWebsite": { "type": "object", "properties": { "url": { "type": "string", "example": "https://www.example.com" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Website": { "type": "object", "properties": { "url": { "type": "string", "example": "https://www.example.com" }, "is_active": { "type": "boolean", "example": true }, "domain": { "$ref": "#/components/schemas/DomainInformation" }, "subdomains": { "type": "array", "items": { "type": "string" } }, "content": { "$ref": "#/components/schemas/WebsiteContent" }, "e_commerce": { "type": "object", "properties": { "product_count": { "type": "integer", "example": 2000 }, "category_count": { "type": "integer", "example": 899 }, "prices": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "example": "EUR" }, "percentiles": { "type": "object", "properties": { "10": { "type": "string", "example": "8.99" }, "20": { "type": "string", "example": "14.99" }, "30": { "type": "string", "example": "19.90" }, "40": { "type": "string", "example": "24.99" }, "50": { "type": "string", "example": "31.92" }, "60": { "type": "string", "example": "41.30" }, "70": { "type": "string", "example": "55.00" }, "80": { "type": "string", "example": "75.00" }, "90": { "type": "string", "example": "129.99" } } }, "median": { "type": "string", "example": "31.92" }, "average": { "type": "string", "example": "55.38" }, "standard_deviation": { "type": "string", "example": "75.45" }, "min": { "type": "string", "example": "0.01" }, "max": { "type": "string", "example": "1299.00" } } } }, "platform": { "type": "string", "example": "SHOPIFY" } } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "WebsiteContent": { "type": "object", "properties": { "title": { "type": "string", "example": "Spyra" }, "description": { "type": "string", "example": "Publisher efficient Urology learning materials. Our books let Urologists focus on what matters." }, "screenshot": { "type": "string", "example": "https://www.example.com/screenshot.png" }, "links": { "type": "object", "properties": { "privacy_policy": { "type": "string", "example": "https://www.example.com/privacy-policy" }, "terms_of_service": { "type": "string", "example": "https://www.example.com/terms-of-service" }, "return_policy": { "type": "string", "example": "https://www.example.com/return-policy" }, "refund_policy": { "type": "string", "example": "https://www.example.com/refund-policy" }, "shipping_policy": { "type": "string", "example": "https://www.example.com/shipping-policy" }, "imprint": { "type": "string", "example": "https://www.example.com/imprint" }, "placeholder_text": { "type": "boolean", "example": false } } } } }, "Profile": { "$ref": "#/components/schemas/BaseProfile" }, "BaseProfile": { "type": "object", "required": [ "provider", "data", "sources" ], "properties": { "provider": { "type": "string", "description": "The name of the provider.", "example": "google" }, "data": { "type": "object", "description": "The data related to the profile." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Name": { "type": "object", "properties": { "name": { "type": "string", "example": "Billie GmbH" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "PhoneNumber": { "type": "object", "properties": { "phone_number": { "type": "string", "example": "+1 234-567-8900" }, "is_valid": { "type": "boolean", "example": true }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Email": { "type": "object", "properties": { "email": { "type": "string", "example": "example@example.com" }, "is_valid": { "type": "boolean", "example": true }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "IdentificationNumber": { "type": "object", "properties": { "type": { "type": "string", "example": "VAT" }, "number": { "type": "string", "example": "123456789" } }, "required": [ "type", "number" ] }, "ContactPerson": { "type": "object", "description": "Contact person details. At least one of 'name' or 'email' must be provided if the object exists.", "properties": { "name": { "type": "string", "nullable": true, "minLength": 1, "description": "Name of the contact person" }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Email address of the contact person" }, "country_code": { "type": "string", "nullable": true, "description": "Country code of the contact person" }, "address": { "type": "string", "nullable": true, "description": "Address of the contact person" }, "phone_number": { "type": "string", "nullable": true, "description": "Phone number of the contact person" } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "email" ] }, { "required": [ "phone_number" ] } ] }, "MonitoringRequest": { "type": "object", "required": [ "website", "checks", "frequency" ], "properties": { "website": { "type": "string", "format": "uri", "description": "The website URL to monitor", "example": "https://example.com" }, "checks": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "non_operational_website", "high_risk_mcc", "high_risk_diligent_classification", "catalog_contain_loan_flipping_indicators" ] }, "description": "Array of monitoring checks to perform", "example": [ "non_operational_website", "high_risk_diligent_classification" ] }, "frequency": { "type": "string", "enum": [ "weekly", "every_2_weeks", "every_3_weeks", "every_4_weeks" ], "default": "every_2_weeks", "description": "How often to run the monitoring checks", "example": "weekly" }, "run_now": { "type": "boolean", "default": true, "description": "Whether to execute the monitoring immediately after creation" }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional expiration date for the monitoring (defaults to 6 months from creation)", "example": "2024-12-31T23:59:59.000Z" }, "skip_duplicate": { "type": "boolean", "description": "If an existing, active monitoring exist with the same site skip don't fail", "example": false } } }, "Monitoring": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique monitoring identifier", "example": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4" }, "website": { "type": "string", "format": "uri", "description": "The monitored website URL", "example": "https://example.com" }, "customer_id": { "type": "string", "description": "Customer identifier" }, "checks": { "type": "array", "items": { "type": "string", "enum": [ "non_operational_website", "high_risk_diligent_classification", "catalog_contain_loan_flipping_indicators" ] }, "description": "Active monitoring checks" }, "frequency": { "type": "string", "enum": [ "weekly", "every_2_weeks", "every_3_weeks", "every_4_weeks" ], "description": "Monitoring frequency" }, "is_active": { "type": "boolean", "description": "Whether monitoring is active" }, "running_state": { "type": "string", "enum": [ "IDLE", "RUNNING", "FAILED" ], "description": "Current execution state" }, "next_run_at": { "type": "string", "format": "date-time", "description": "Next scheduled execution time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Monitoring expiration date" }, "last_execution": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of last execution, null if never executed" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "execution_results": { "type": "array", "items": { "type": "object" }, "description": "Results from the latest monitoring execution" }, "external_id": { "type": "string", "description": "External identifier for this monitoring" } } }, "ScreeningResponse": { "type": "object", "required": [ "run_id", "website", "screened_at", "platform", "operational_status" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for this screening run", "example": "run_123456789" }, "website": { "type": "string", "format": "uri", "example": "https://example-store.com" }, "screened_at": { "type": "string", "format": "date-time", "example": "2025-03-31T12:34:56Z" }, "platform": { "type": "string", "enum": [ "SHOPIFY", "WOOCOMMERCE", "NOPCOMMERCE", "ZID", "SALLA", "WIZISHOP", "MAGENTO", "OXID", "PRESTASHOP", "CUSTOM" ], "description": "Detected platform of the website", "example": "SALLA" }, "operational_status": { "type": "object", "required": [ "is_active", "explanation" ], "properties": { "is_active": { "type": "boolean", "example": false }, "explanation": { "type": "string", "example": "The message indicates that the store is currently under maintenance, which is a clear indicator of a non-operational status." } } } } } }, "securitySchemes": { "xApiKey": { "type": "apiKey", "name": "X-API-KEY", "in": "header" } } } }