{ "openapi": "3.1.0", "info": { "title": "EntityReach Workflow API", "version": "1.1.0", "description": "Reusable company matching, corporate-group discovery and scheduled monitoring. Bearer keys require workflows:write. Workflows require active Business, Scale or Enterprise allowances. See the integration guide for async states and metering." }, "servers": [ { "url": "https://entityreach.com/api/v1" } ], "security": [ { "WorkspaceKey": [] } ], "externalDocs": { "url": "https://entityreach.com/docs/workflows" }, "paths": { "/workflows": { "post": { "summary": "Create a reusable expansion workflow", "operationId": "post__workflows", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Public HTTPS receiver; notification payloads contain identifiers only." }, "monitoring": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "company", "group" ], "default": "group" }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "company.name", "company.status", "company.registration_number", "company.vat", "company.address_street", "company.email", "company.phone", "company.fax", "company.website", "company.bank", "company.employees_number", "company.trading_activity_export", "company.trading_activity_import", "company.group_structure", "company.financial", "office.identity", "office.email", "office.fax", "office.phone", "office.website", "address.street", "shareholder.holding", "shareholder.holding_historical", "shareholder.exit_precise", "shareholder.exit_approximate", "shareholder.share_type", "shareholder.share_price", "employee.appointment", "employee.phone", "employee.email", "employee.resignation_date", "officer.appointment", "officer.phone", "officer.email", "officer.resignation_date" ] }, "minItems": 1, "maxItems": 35, "default": [ "company.group_structure", "company.status" ] }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ], "default": "daily" }, "max_companies": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "auto_enrol": { "type": "boolean", "default": true } } } } } } } }, "responses": { "201": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List workflow definitions", "operationId": "get__workflows", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Pass the preceding next_cursor. Events start at 0; lists start without a cursor." } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/fields": { "get": { "summary": "List supported monitoring fields and defaults", "operationId": "get__workflows_fields", "parameters": [], "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}": { "get": { "summary": "Read a workflow", "operationId": "get__workflows_workflow_id_", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit configuration, pause, resume or permanently stop a workflow", "operationId": "patch__workflows_workflow_id_", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "paused", "stopped" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "config", "expected_updated_at" ], "properties": { "config": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Public HTTPS receiver; notification payloads contain identifiers only." }, "monitoring": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "company", "group" ], "default": "group" }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "company.name", "company.status", "company.registration_number", "company.vat", "company.address_street", "company.email", "company.phone", "company.fax", "company.website", "company.bank", "company.employees_number", "company.trading_activity_export", "company.trading_activity_import", "company.group_structure", "company.financial", "office.identity", "office.email", "office.fax", "office.phone", "office.website", "address.street", "shareholder.holding", "shareholder.holding_historical", "shareholder.exit_precise", "shareholder.exit_approximate", "shareholder.share_type", "shareholder.share_price", "employee.appointment", "employee.phone", "employee.email", "employee.resignation_date", "officer.appointment", "officer.phone", "officer.email", "officer.resignation_date" ] }, "minItems": 1, "maxItems": 35, "default": [ "company.group_structure", "company.status" ] }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ], "default": "daily" }, "max_companies": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "auto_enrol": { "type": "boolean", "default": true } } } } }, "expected_updated_at": { "type": "string", "format": "date-time" } } } ] } } } }, "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/companies": { "post": { "summary": "Enrol a company", "operationId": "post__workflows_workflow_id_companies", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "A stable key for this company submission. Reusing it with different input returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "company" ], "properties": { "company": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "company_id" }, "value": { "type": "string", "pattern": "^[0-9]{1,20}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "name" }, "value": { "type": "string", "minLength": 2, "maxLength": 200 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value", "country" ], "properties": { "type": { "const": "registration" }, "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value", "country" ], "properties": { "type": { "const": "vat" }, "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "website" }, "value": { "type": "string", "minLength": 1, "maxLength": 253 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } } ] } } } } } }, "responses": { "202": { "description": "Company enrolment accepted for background processing.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List company enrolments", "operationId": "get__workflows_workflow_id_companies", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Pass the preceding next_cursor. Events start at 0; lists start without a cursor." } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/companies/{enrolment_id}": { "get": { "summary": "Read company progress, group, relationships and monitoring coverage", "operationId": "get__workflows_workflow_id_companies_enrolment_id_", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enrolment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Enrolment" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Pause, resume or stop an enrolment", "operationId": "patch__workflows_workflow_id_companies_enrolment_id_", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enrolment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "paused", "stopped" ] } } } } } }, "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/companies/{enrolment_id}/confirm": { "post": { "summary": "Confirm a returned candidate", "operationId": "post__workflows_workflow_id_companies_enrolment_id_confirm", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enrolment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "company_id" ], "properties": { "company_id": { "type": "string", "pattern": "^[0-9]{1,20}$" } } } } } }, "responses": { "202": { "description": "Company enrolment accepted for background processing.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/events": { "get": { "summary": "Read events and delivery status", "operationId": "get__workflows_workflow_id_events", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "integer" }, "description": "Pass the preceding next_cursor. Events start at 0; lists start without a cursor." } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/events/{event_id}/replay": { "post": { "summary": "Requeue a webhook delivery", "operationId": "post__workflows_workflow_id_events_event_id_replay", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/usage": { "get": { "summary": "Read monitoring coverage and delivery health", "operationId": "get__workflows_workflow_id_usage", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/webhook/test": { "post": { "summary": "Queue a signed test notification", "operationId": "post__workflows_workflow_id_webhook_test", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "202": { "description": "Company enrolment accepted for background processing.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflow_id}/webhook/rotate-secret": { "post": { "summary": "Rotate the signing secret; replacement is returned once", "operationId": "post__workflows_workflow_id_webhook_rotate_secret", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation.", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining monthly API requests." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The operation was rejected. Read the error message and HTTP status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "WorkspaceKey": { "type": "http", "scheme": "bearer", "description": "EntityReach er_live_ key with workflows:write permission." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Usage": { "type": "object", "required": [ "used", "limit", "period" ], "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "period": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" } } }, "Envelope": { "type": "object", "properties": { "data": {}, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "integer", "null" ] }, "has_more": { "type": "boolean" } } }, "WorkflowInput": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Public HTTPS receiver; notification payloads contain identifiers only." }, "monitoring": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "company", "group" ], "default": "group" }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "company.name", "company.status", "company.registration_number", "company.vat", "company.address_street", "company.email", "company.phone", "company.fax", "company.website", "company.bank", "company.employees_number", "company.trading_activity_export", "company.trading_activity_import", "company.group_structure", "company.financial", "office.identity", "office.email", "office.fax", "office.phone", "office.website", "address.street", "shareholder.holding", "shareholder.holding_historical", "shareholder.exit_precise", "shareholder.exit_approximate", "shareholder.share_type", "shareholder.share_price", "employee.appointment", "employee.phone", "employee.email", "employee.resignation_date", "officer.appointment", "officer.phone", "officer.email", "officer.resignation_date" ] }, "minItems": 1, "maxItems": 35, "default": [ "company.group_structure", "company.status" ] }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ], "default": "daily" }, "max_companies": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "auto_enrol": { "type": "boolean", "default": true } } } } }, "CompanyInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "company_id" }, "value": { "type": "string", "pattern": "^[0-9]{1,20}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "name" }, "value": { "type": "string", "minLength": 2, "maxLength": 200 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value", "country" ], "properties": { "type": { "const": "registration" }, "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value", "country" ], "properties": { "type": { "const": "vat" }, "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "website" }, "value": { "type": "string", "minLength": 1, "maxLength": 253 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } } ] }, "Enrolment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "company": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "company_id" }, "value": { "type": "string", "pattern": "^[0-9]{1,20}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "name" }, "value": { "type": "string", "minLength": 2, "maxLength": 200 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value", "country" ], "properties": { "type": { "const": "registration" }, "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value", "country" ], "properties": { "type": { "const": "vat" }, "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "website" }, "value": { "type": "string", "minLength": 1, "maxLength": 253 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } } } ] }, "company_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "needs_confirmation", "ready", "not_found", "duplicate", "failed", "paused", "stopped" ] }, "phase": { "type": "string" }, "candidates": { "type": "array", "items": { "type": "object" } }, "group": { "type": [ "object", "null" ], "description": "Last complete group snapshot. Unavailable financial or headcount facts are omitted." }, "result": { "type": [ "object", "null" ], "description": "Related companies, relationships and observed changes, or existing_enrolment_id for a duplicate." }, "monitoring": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "error" ] }, "error": { "type": [ "string", "null" ] }, "last_poll": { "type": [ "string", "null" ] } } } }, "last_error": { "type": [ "string", "null" ] }, "next_check_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }