{ "openapi": "3.1.0", "info": { "title": "epv invoice requests", "version": "epv-public-affairs-2026.10.18.1", "description": "Current engagements use invoice requests and owner-verified bank payment. Private order and intake access requires the retained bearer. Saving a request neither charges nor reserves a start. Native ChatGPT and Meta checkout is not enrolled." }, "servers": [ { "url": "https://epv.ai" } ], "paths": { "/api/v1/public-affairs-offers": { "get": { "operationId": "getEngagements", "summary": "Read current scope, fees and service terms", "security": [], "responses": { "200": { "description": "Read current scope, fees and service terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalogue" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/quotes": { "post": { "operationId": "quoteEngagement", "summary": "Prepare a server-priced quote without charge or reservation", "security": [], "responses": { "201": { "description": "Prepare a server-priced quote without charge or reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "fictional_matter_quote": { "summary": "Fictional one-matter quote request", "description": "Syntax example only. A real caller supplies the actual authorised organisation and reads the current service terms. Use the returned quote credentials and transaction terms version for its invoice request; do not invent those values.", "value": { "offer_id": "epv", "scope": { "offer": "epv", "kind": "epv_public_affairs", "answers": { "service": "matter", "business": "Example Association", "question": "Which official decision changed, and what must the client know before the next meeting?", "jurisdiction": "Example Canadian public body", "records_outline": "One official agenda, the published minutes and one supplied correspondence record.", "deadline": "Before the next scheduled client meeting.", "authority": "confirmed", "billing_authority": "confirmed", "service_terms": "epv-public-affairs-2026.10.18.1", "service_month": "" }, "result": [] } } } } } } } } }, "/api/v1/orders": { "post": { "operationId": "requestInvoice", "summary": "Save an authorised invoice request without payment or reservation", "security": [], "responses": { "201": { "description": "Save an authorised invoice request without payment or reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedRequest" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Identical retry returns the original retained record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedRequest" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Retain this key and exact body until the save is known. Never rotate after an uncertain commit." } ] } }, "/api/v1/orders/{order_id}": { "get": { "operationId": "readPrivateRequest", "summary": "Read the private invoice, instructions and verified receipt", "security": [ { "orderAccess": [] } ], "responses": { "200": { "description": "Read the private invoice, instructions and verified receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRecord" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/api/v1/orders/{order_id}/interac": { "post": { "operationId": "acceptInvoiceInstructions", "summary": "Accept the exact invoice and retain approved bank instructions without moving money", "security": [ { "orderAccess": [] } ], "responses": { "200": { "description": "Accept the exact invoice and retain approved bank instructions without moving money", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInstructions" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceAcceptance" } } } }, "description": "Requires buyer authority, the exact active invoice and matching owner-confirmed payment destination. Confirms capacity for an initial review and records one bank-payment attempt. Does not transfer money, create a receipt or start the delivery clock. An identical retry returns the retained instructions." }, "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/api/v1/orders/{order_id}/cancel": { "post": { "operationId": "cancelUnpaidRequest", "summary": "Cancel an authorised unpaid request before any payment attempt", "security": [ { "orderAccess": [] } ], "responses": { "200": { "description": "Cancel an authorised unpaid request before any payment attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelledRequest" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } }, "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/api/v1/epv-enquiries": { "post": { "operationId": "sendCustomEnquiry", "summary": "Record a custom enquiry without billing, order or booking", "security": [], "responses": { "201": { "description": "Record a custom enquiry without billing, order or booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnquiryReceipt" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Identical retry returns the original retained record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnquiryReceipt" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enquiry" }, "examples": { "fictional_enquiry": { "summary": "Fictional custom-scope enquiry", "description": "Syntax example only, not a production test. Send a real enquiry only with the person's authority and retain its original Idempotency-Key and exact body through interruption.", "value": { "organisation": "Example Association", "email": "purchasing@example.invalid", "question": "We need a brief on one Canadian consultation and its remaining deadlines." } } } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Retain this key and exact body until the save is known. Never rotate after an uncertain commit." } ] } }, "/api/v1/orders/{order_id}/service-intake": { "post": { "operationId": "savePaidMatterOutline", "summary": "Retain an outline revision without marking records complete or starting work", "security": [ { "orderAccess": [] } ], "responses": { "200": { "description": "Retain an outline revision without marking records complete or starting work", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeRecord" } } } }, "400": { "description": "Invalid JSON, missing fields or a local rehearsal that cannot accept payment instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or access rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or unauthorised quote or private order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Scope, terms, expiry, idempotency, tax, capacity or state conflict. Resolve before continuing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Missing or excessive body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Wait at least 60 seconds before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Uncertain server failure. Preserve the exact body and key for retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The release or an authorised service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "The gateway could not finish reading this request body and did not forward it. Keep the original body and Idempotency-Key for an order or enquiry retry. This response does not establish a payment or a saved record. An unfamiliar or ambiguous response still requires readback where a private link is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The upstream response could not be confirmed. The request may already have reached the service. Keep the exact body and Idempotency-Key; read the existing private record where available, or retry the same order or enquiry request. Do not rotate a key, create another request or treat the response as proof that nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The gateway forwarded the request but could not confirm the response within its deadline. The save may have committed. Keep the exact body and Idempotency-Key; use private readback where available, or retry the same order or enquiry request. Reconcile an uncertain invoice instruction against the same invoice. A timeout does not confirm cancellation, payment, receipt or the start of work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceIntake" } } } } }, "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "x-epv-historical-contracts": { "seller_and_terms_retained": true, "new_purchases_use_current_contract": true, "instruction": "Earlier private order links and original payment recovery remain supported. Current purchase operations do not offer a provider checkout. Historical records may omit current invoice-only fields." }, "components": { "schemas": { "Scope": { "type": "object", "properties": { "offer": { "const": "epv" }, "kind": { "const": "epv_public_affairs" }, "answers": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "matter", "installation", "desk" ] }, "business": { "type": "string", "minLength": 1, "maxLength": 180 }, "question": { "type": "string", "minLength": 1, "maxLength": 1200 }, "jurisdiction": { "type": "string", "minLength": 1, "maxLength": 160 }, "authority": { "const": "confirmed" }, "service_terms": { "const": "epv-public-affairs-2026.10.18.1" }, "records_outline": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "General list only. No credentials or confidential source contents." }, "deadline": { "type": "string", "maxLength": 160, "description": "A fixed date or timing constraint if one exists; otherwise empty." }, "billing_authority": { "const": "confirmed" }, "service_month": { "type": "string", "description": "YYYY-MM for the named desk month; empty for either one-time engagement." } }, "required": [ "service", "business", "question", "jurisdiction", "authority", "service_terms", "records_outline", "deadline", "billing_authority", "service_month" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "service": { "const": "desk" } } }, "then": { "properties": { "service_month": { "pattern": "^20[0-9]{2}-(0[1-9]|1[0-2])$" } } }, "else": { "properties": { "service_month": { "const": "" } } } } ] }, "product": { "type": "string", "description": "Optional client label; the server replaces it with the catalogue name." }, "result": { "type": "array", "maxItems": 120, "items": { "type": "string", "maxLength": 1500 }, "description": "An empty array is sufficient. The server owns the scope, deliverables and fee." } }, "required": [ "offer", "kind", "answers", "result" ], "additionalProperties": false }, "Billing": { "type": "object", "properties": { "country": { "enum": [ "CA", "US" ] }, "region": { "type": "string", "minLength": 1, "maxLength": 80 }, "address": { "type": "string", "minLength": 8, "maxLength": 300, "description": "Single-line street and city for the contracting business address most closely connected with this service." }, "postal_code": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "country", "region", "address", "postal_code" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1 } }, "required": [ "error" ] }, "Catalogue": { "type": "object", "properties": { "name": { "const": "epv" }, "seller": { "const": "Data Vision IT Services Inc." }, "currency": { "const": "CAD" }, "service_terms_version": { "const": "epv-public-affairs-2026.10.18.1" }, "service_payment_mode": { "const": "invoice_only" }, "invoice_request_only": { "const": true }, "service_offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "enum": [ "matter", "installation", "desk" ] }, "name": { "type": "string", "minLength": 1 }, "price_cents": { "type": "integer", "minimum": 1 }, "currency": { "const": "CAD" }, "scope": { "type": "string", "minLength": 1 }, "deliverables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "delivery": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "price_cents", "currency", "scope", "deliverables", "delivery" ] } }, "automatic_recurring_billing": { "const": false } }, "required": [ "name", "seller", "currency", "service_terms_version", "service_payment_mode", "invoice_request_only", "service_offers", "automatic_recurring_billing" ] }, "QuoteRequest": { "type": "object", "properties": { "offer_id": { "const": "epv" }, "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "offer_id", "scope" ], "additionalProperties": false }, "Quote": { "type": "object", "properties": { "quote_id": { "type": "string", "minLength": 1 }, "quote_token": { "type": "string", "minLength": 1 }, "expires_at": { "type": "integer", "description": "Unix seconds; quote lasts 30 minutes." }, "terms_version": { "type": "string", "minLength": 1 }, "service_terms_version": { "const": "epv-public-affairs-2026.10.18.1" }, "service_offer": { "type": "object" }, "service_price_cents": { "type": "integer", "minimum": 0 }, "currency": { "const": "CAD" }, "invoice_required": { "const": true }, "payable": { "const": false }, "service_payment_mode": { "const": "invoice_only" }, "invoice_request_only": { "const": true }, "tax_cents": { "type": "null" }, "total_cents": { "type": "null" }, "automatic_recurring_billing": { "const": false } }, "required": [ "quote_id", "quote_token", "expires_at", "terms_version", "service_terms_version", "service_offer", "service_price_cents", "currency", "invoice_required", "payable", "service_payment_mode", "invoice_request_only", "tax_cents", "total_cents", "automatic_recurring_billing" ] }, "OrderRequest": { "type": "object", "properties": { "quote_id": { "type": "string", "minLength": 1 }, "quote_token": { "type": "string", "minLength": 1 }, "terms_version": { "type": "string", "minLength": 1, "description": "Copy the quote transaction terms_version, not its service_terms_version." }, "name": { "type": "string", "minLength": 1, "maxLength": 180, "description": "Copy scope.answers.business exactly. This is the billing organisation, not an invented contact person." }, "email": { "type": "string", "minLength": 1, "format": "email", "maxLength": 254 }, "consent": { "const": true }, "billing": { "$ref": "#/components/schemas/Billing" } }, "required": [ "quote_id", "quote_token", "terms_version", "name", "email", "consent", "billing" ], "additionalProperties": false }, "SavedRequest": { "type": "object", "properties": { "order_id": { "type": "string", "minLength": 1 }, "reference": { "type": "string", "minLength": 1 }, "status": { "enum": [ "requested", "invoice_ready" ] }, "order_url": { "type": "string", "minLength": 1, "description": "Private same-origin /order/ URL. Its fragment contains order_id.bearer_token; never publish it." }, "service_price_cents": { "type": "integer", "minimum": 0 }, "service_terms_version": { "type": "string", "minLength": 1 }, "currency": { "const": "CAD" }, "invoice_required": { "const": true }, "payable": { "const": false }, "tax_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "total_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "service_payment_mode": { "type": "string", "minLength": 1 }, "invoice_request_only": { "type": "boolean" }, "automatic_recurring_billing": { "const": false } }, "required": [ "order_id", "reference", "status", "order_url", "service_price_cents", "currency", "invoice_required", "payable", "automatic_recurring_billing" ], "allOf": [ { "if": { "required": [ "service_terms_version" ], "properties": { "service_terms_version": { "const": "epv-public-affairs-2026.10.18.1" } } }, "then": { "required": [ "service_payment_mode", "invoice_request_only" ], "properties": { "service_payment_mode": { "const": "invoice_only" }, "invoice_request_only": { "const": true }, "payable": { "const": false }, "paypal_available": { "const": false } } } } ] }, "Invoice": { "type": "object", "properties": { "invoice_id": { "type": "string", "minLength": 1 }, "order_reference": { "type": "string", "minLength": 1 }, "seller": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "minLength": 1 }, "currency": { "const": "CAD" }, "subtotal_cents": { "type": "integer", "minimum": 0 }, "tax_cents": { "type": "integer", "minimum": 0 }, "total_cents": { "type": "integer", "minimum": 0 }, "gst_cents": { "type": "integer", "minimum": 0 }, "pst_cents": { "type": "integer", "minimum": 0 }, "terms_version": { "type": "string", "minLength": 1 }, "delivery_terms": { "type": "string", "minLength": 1 }, "cancellation_terms": { "type": "string", "minLength": 1 }, "recurring": { "const": false }, "approved_at": { "type": "integer" }, "billing_organisation": { "type": "string", "minLength": 1 }, "billing_address": { "type": "string", "minLength": 1 }, "billing_postal_code": { "type": "string", "minLength": 1 }, "billing_country": { "type": "string", "minLength": 1 }, "billing_region": { "type": "string", "minLength": 1 }, "gst_registration": { "type": "string", "minLength": 1 }, "pst_registration": { "type": "string", "minLength": 1 }, "service_payment_mode": { "const": "invoice_only" } }, "required": [ "invoice_id", "order_reference", "seller", "scope", "currency", "subtotal_cents", "tax_cents", "total_cents", "terms_version", "delivery_terms", "cancellation_terms", "recurring" ], "allOf": [ { "if": { "required": [ "service_payment_mode" ], "properties": { "service_payment_mode": { "const": "invoice_only" } } }, "then": { "required": [ "billing_organisation", "gst_cents", "pst_cents", "gst_registration", "pst_registration" ], "properties": { "seller": { "const": "Data Vision IT Services Inc." }, "gst_registration": { "const": "815332705RT0001" }, "pst_registration": { "const": "PST-1003-5641" } } } } ] }, "BankInstructions": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "format": "email" }, "recipient": { "type": "string", "minLength": 1 } }, "required": [ "email", "recipient" ] }, "InvoiceAcceptance": { "type": "object", "properties": { "invoice_id": { "type": "string", "minLength": 1 }, "consent": { "const": true } }, "required": [ "invoice_id", "consent" ], "additionalProperties": false }, "InvoiceInstructions": { "type": "object", "properties": { "interac": { "$ref": "#/components/schemas/BankInstructions" }, "status": { "const": "awaiting_bank_verification" } }, "required": [ "interac", "status" ] }, "Receipt": { "type": "object", "properties": { "order_id": { "type": "string", "minLength": 1 }, "transaction_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "amount_cents": { "type": "integer", "minimum": 0 }, "currency": { "const": "CAD" }, "created": { "type": "integer" } }, "required": [ "order_id", "transaction_id", "provider", "amount_cents", "currency", "created" ] }, "OrderRecord": { "type": "object", "properties": { "order_id": { "type": "string", "minLength": 1 }, "reference": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "scope": { "type": "object" }, "currency": { "const": "CAD" }, "service_price_cents": { "type": "integer", "minimum": 0 }, "service_terms_version": { "type": "string", "minLength": 1 }, "payable": { "type": "boolean" }, "invoice": { "anyOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "null" } ] }, "receipt": { "anyOf": [ { "$ref": "#/components/schemas/Receipt" }, { "type": "null" } ] }, "tax_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "total_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "service_payment_mode": { "type": "string", "minLength": 1 }, "invoice_request_only": { "type": "boolean" }, "invoice_payment_available": { "type": "boolean" }, "interac_available": { "type": "boolean" }, "interac": { "anyOf": [ { "$ref": "#/components/schemas/BankInstructions" }, { "type": "null" } ] }, "payment_instructions_status": { "enum": [ "invoice_pending", "seller_confirmation_required", "review_place_unavailable", "available_on_acceptance", "issued", "paid", "refunded", "request_closed", "payment_attempt_closed", "reconciliation_required" ] }, "paypal_available": { "type": "boolean", "description": "False for current invoice-only contracts. Retained earlier contracts may report their original method." }, "paypal_state": { "type": [ "object", "null" ], "description": "Historical provider state only; it is not a payment action for current contracts." }, "service_intake": { "type": [ "object", "null" ] }, "service_intake_required": { "type": "boolean" }, "service_intake_available": { "type": "boolean" }, "automatic_recurring_billing": { "const": false } }, "required": [ "order_id", "reference", "status", "scope", "payable", "invoice", "receipt", "interac_available", "interac", "paypal_available", "paypal_state", "service_intake", "service_intake_required", "service_intake_available" ], "allOf": [ { "if": { "required": [ "service_terms_version" ], "properties": { "service_terms_version": { "const": "epv-public-affairs-2026.10.18.1" } } }, "then": { "required": [ "service_payment_mode", "invoice_request_only" ], "properties": { "service_payment_mode": { "const": "invoice_only" }, "invoice_request_only": { "const": true }, "payable": { "const": false }, "paypal_available": { "const": false } } } } ] }, "CancelledRequest": { "type": "object", "properties": { "status": { "const": "cancelled" }, "message": { "type": "string", "minLength": 1 } }, "required": [ "status", "message" ] }, "Enquiry": { "type": "object", "properties": { "organisation": { "type": "string", "minLength": 1, "maxLength": 180 }, "email": { "type": "string", "minLength": 1, "format": "email", "maxLength": 254 }, "question": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "organisation", "email", "question" ], "additionalProperties": false }, "EnquiryReceipt": { "type": "object", "properties": { "enquiry_id": { "type": "string", "minLength": 1 }, "reference": { "type": "string", "minLength": 1 }, "status": { "const": "received" }, "message": { "type": "string", "minLength": 1 } }, "required": [ "enquiry_id", "reference", "status", "message" ] }, "ServiceIntake": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 20 }, "question": { "type": "string", "minLength": 1, "maxLength": 1200 }, "jurisdiction": { "type": "string", "minLength": 1, "maxLength": 160 }, "records_outline": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "revision", "question", "jurisdiction", "records_outline" ], "additionalProperties": false }, "IntakeRecord": { "type": "object", "properties": { "service_intake": { "type": "object" }, "service_intake_required": { "type": "boolean" }, "service_intake_available": { "type": "boolean" } }, "required": [ "service_intake", "service_intake_required", "service_intake_available" ] } }, "securitySchemes": { "orderAccess": { "type": "http", "scheme": "bearer", "description": "Token from the private order_url fragment. Never include it in query strings, logs or shared output." }, "reviewAccess": { "type": "apiKey", "in": "cookie", "name": "__Host-xxv_review", "description": "Existing authorised review session; no bypass or new access is provided by this contract." } } }, "x-epv-client-guidance": { "identity": "HTTP clients should identify their actual software truthfully with a normal User-Agent and a contact or documentation URL where available. Browsers keep their normal identity. Do not impersonate a browser, search crawler or another service to avoid a rejection.", "access": "A public catalogue does not authorise a purchase. Obtain the buyer's authority, use the documented same-origin workflow, and retain the private bearer only for that buyer's record. A 403 is an access rejection to resolve, not permission to bypass it.", "uncertainty": "Keep one Idempotency-Key and the exact request body until an order or enquiry outcome is known. Request readback and invoice instruction acceptance use the existing private credential and record. No client endpoint confirms bank settlement.", "examples": "The two request examples are fictional syntax only. They establish no buyer authority and must not be submitted as production tests." } }