{ "servers": [ { "url": "https://api.datawollet.com", "description": "Production (uses live data)" }, { "url": "https://api.sandbox.datawollet.com", "description": "Sandbox (supports a subset of document types)" }, { "url": "http://localhost:8081", "description": "Development (DataWollet team only)" }, { "url": "https://api.dev.datawollet.com", "description": "Development (DataWollet and invited users only)" } ], "info": { "title": "DataWollet Open Finance API", "version": "1.80.26", "description": "\n The DataWollet Open Finance API provides secure document data extraction and open banking connectivity services. It is part of DataWollet's Open Finance\n solution, enabling clients to extract structured data from documents and connect to banking data through regulated Account Information Service\n Providers (AISPs).\n\n Using these APIs it is possible to extract data from a wide range of document types including bank statements, utility bills, identity documents,\n council tax bills, mortgage statements, mortgage illustrations, insurance proposals and schedules, and more.\n\n This API supports multiple authentication models:\n - **API Key Authentication**: For server-to-server communication, clients can use API keys to authenticate requests. API keys are associated with specific\n clients and scopes, controlling access to API features. DataWollet no longer issues API keys to new clients; instead, OAuth2 client credentials are the\n preferred method.\n\n - **OAuth2 Client Credentials Grant**: For machine-to-machine authentication, clients can obtain access tokens using the OAuth2 client credentials grant flow.\n This method is recommended for new integrations and provides enhanced security and flexibility. Tokens shoud be obtained from\n [the token endpoint](/docs/data-api/post-oauth-token).\n\n - **Bearer Tokens from Identity Providers**: For user-based authentication, bearer tokens issued by DataWollet's user identity providers can be used to access\n the API on behalf of users. Users may be individuals managing their own data as part of a wallet through the DataWollet Open Finance platform, the\n end-users of tenants integrating DataWollet services into their applications, or users of DataWollet's turnkey applications.\n * **Internal users** and clients should authenticate against `authentication.datawollet.com`.\n * **External users** managing their own data should authenticate against `identity.wallet.datawollet.com`.\n\n - **Validated Public Client**: For session-only operations on third-party websites, such as when using DataWollet's Web Library. The client is identified\n and validated based on the origin of the request. A valid client ID is still required and must be passed when initiating a session. Public clients are\n restricted to session-based operations and cannot access wallet storage, open banking, or identity verification features. Persistence of the data is expected\n to take place on the client side, with limited data retained by DataWollet only to enable the session functionality.\n\n " }, "tags": [ { "name": "oauth2", "description": "Authentication methods for obtaining access tokens", "x-displayName": "Authentication" }, { "name": "session", "description": "Persistent session to extract from multiple documents, and to retrieve data extracted on subsequent page loads.", "x-displayName": "Session" }, { "name": "documents", "description": "Extract structured data from documents, either captured as scan images or as binary document sources.", "x-displayName": "Documents" }, { "name": "graph", "description": "Create and manage knowledge graphs from extracted document data, including graph fusion and node deduplication.", "x-displayName": "Graph and fusion" }, { "name": "ais", "description": "Open banking connections", "x-displayName": "Open banking" }, { "name": "identity", "description": "Identity Verification", "x-displayName": "Identity" }, { "name": "storage", "description": "Wallet storage operations", "x-displayName": "Storage" }, { "name": "settings", "description": "Portal configuration and branding settings", "x-displayName": "Settings" }, { "name": "envelope", "description": "Encrypted cross-session document storage with access control", "x-displayName": "Envelopes" } ], "openapi": "3.0.0", "components": { "securitySchemes": { "API key": { "type": "apiKey", "scheme": "ApiKey", "name": "Authorization", "in": "header", "description": "Send the `ApiKey` scheme name and the key supplied by DataWollet, separated by a space, within the `Authorization` header" }, "Bearer token": { "type": "oauth2", "scheme": "Bearer", "description": "Send the `Bearer` scheme name and the OAuth2 access token, separated by a space, within the `Authorization` header", "flows": { "clientCredentials": { "tokenUrl": "https://authentication.datawollet.com/oauth2/token", "scopes": { "documents:initiate": "Extract data from documents submitted", "documents:write": "Retain documents as part of a session using DataWollet's secure session-based storage", "documents:read": "Download retained source files from extraction sessions", "documents:ocr": "Use documents that do not contain embedded text (e.g. scanned images) with OCR processing", "sessions:read": "Retrieve requests and documents previously stored in a session", "sessions:write": "Start and manage a session to allow multiple document submissions, AIS or identity operations", "enrichments:transactions": "Additional processing for banking transaction data to provide categorisation, merchant and processor data", "events:write": "Store details of user events associated with a session", "websockets:initiate": "Initiate WebSocket connections and request tickets, for real-time session updates", "settings:read": "Read portal configuration and settings", "envelopes:create": "Create new envelopes for cross-session document storage", "envelopes:read": "Read data from envelope-backed sessions", "envelopes:write": "Write data to envelope-backed sessions", "envelopes:acl:read": "Read envelope access control lists", "envelopes:acl:write": "Modify envelope access control lists", "neuro:initiate": "Initiate full neuro-symbolic AI and pipeline on-demand" } }, "authorizationCode": { "authorizationUrl": "https://authentication.datawollet.com/oauth2/authorize", "tokenUrl": "https://authentication.datawollet.com/oauth2/token", "scopes": { "documents:initiate": "Extract data from documents submitted", "documents:write": "Retain documents as part of a session using DataWollet's secure session-based storage", "documents:read": "Download retained source files from extraction sessions", "documents:ocr": "Use documents that do not contain embedded text (e.g. scanned images) with OCR processing", "sessions:read": "Retrieve requests and documents previously stored in a session", "sessions:write": "Start and manage a session to allow multiple document submissions, AIS or identity operations", "enrichments:transactions": "Additional processing for banking transaction data to provide categorisation, merchant and processor data", "events:write": "Store details of user events associated with a session", "wallet:read": "Read wallet storage data", "wallet:write": "Create or modify wallet storage data", "ais:initiate": "Initiate open banking connections", "identity:initiate": "Initiate identity verification processes", "websockets:initiate": "Initiate WebSocket connections and request tickets, for real-time session updates", "settings:read": "Read portal configuration and settings", "envelopes:create": "Create new envelopes for cross-session document storage", "envelopes:read": "Read data from envelope-backed sessions", "envelopes:write": "Write data to envelope-backed sessions", "envelopes:acl:read": "Read envelope access control lists", "envelopes:acl:write": "Modify envelope access control lists", "neuro:initiate": "Initiate full neuro-symbolic AI and pipeline on-demand" } } } } }, "schemas": { "ark:Verification": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Verification", "example": "ark:Verification" }, "verificationType": { "description": "The type of verification performed.", "type": "string", "example": "Identity" }, "relatedTo": { "description": "The identifier of the entities that this verification is related to.", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "https://graph.datawollet.com/.draft-nodes/1234567890abcdef1234567800000000" ] } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:VehicleValuation": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:VehicleValuation", "example": "ark:VehicleValuation" }, "relatedTo": { "description": "The vehicle that this valuation relates to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "date": { "description": "The date of the valuation.", "type": "string", "format": "date", "example": "2026-01-15" }, "value": { "description": "The market value of the vehicle.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "value" ], "additionalProperties": false }, "ark:VehicleSecuritySummary": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:VehicleSecuritySummary", "example": "ark:VehicleSecuritySummary" }, "relatedTo": { "description": "The vehicle that this security information describes.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "securityDevices": { "description": "Information about security devices fitted on the vehicle.", "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "example": "Thatcham category 1" }, "alarm": { "description": "Indicates whether the vehicle has an alarm fitted.", "type": "boolean", "example": true }, "immobiliser": { "description": "Indicates whether the vehicle has an immobiliser fitted.", "type": "boolean", "example": true }, "tracker": { "description": "Indicates whether the vehicle has a tracker fitted.", "type": "boolean", "example": true }, "location": { "description": "The address where the vehicle is kept, either a reference to an address or the policyholder's address.", "anyOf": [ { "type": "string", "format": "uri" }, { "const": "Policyholder's address" } ], "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "overnightLocation": { "description": "Where the vehicle is kept overnight.", "type": "string", "enum": [ "Garage", "Driveway", "Street", "Compound", "Car park", "Property" ], "example": "Garage" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:Vehicle": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Vehicle", "example": "ark:Vehicle" }, "owner": { "description": "The owner of the vehicle, either a reference to a person or a category of owner.", "anyOf": [ { "type": "string", "format": "uri" }, { "enum": [ "Finance Company", "Employer", "Partner", "Parent", "Child", "Other" ] } ], "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "registeredKeeper": { "description": "The owner of the vehicle, either a reference to a person or a category of owner.", "anyOf": [ { "type": "string", "format": "uri" }, { "enum": [ "Finance Company", "Employer", "Partner", "Parent", "Child", "Other" ] } ], "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "vin": { "description": "Vehicle Identification Number (VIN).", "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ3CZWE123456", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "registrationNumber": { "description": "Vehicle registration or licence plate number.", "type": "string", "example": "AB12 CDE", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "imported": { "description": "Indicates whether the vehicle has been imported to the country.", "type": "boolean", "example": false }, "mileage": { "description": "Current odometer reading in miles.", "type": "number", "example": 45000 }, "makeModel": { "description": "Vehicle make and model (e.g., Ford Focus, BMW 3 Series).", "type": "string", "example": "Ford Focus" }, "registrationYear": { "description": "Year the vehicle was first registered.", "type": "string", "pattern": "^[0-9]{4}$", "example": "2020" }, "manufactureYear": { "description": "Year the vehicle was manufactured.", "type": "string", "pattern": "^[0-9]{4}$", "example": "2020" }, "bodyType": { "description": "Body style of the vehicle (e.g., Hatchback, Saloon, Estate, SUV).", "type": "string", "example": "Hatchback" }, "fuelType": { "description": "Fuel or power type of the vehicle.", "type": "string", "enum": [ "Petrol", "Diesel", "Electric", "Hybrid", "LPG" ], "example": "Petrol" }, "numberOfSeats": { "description": "Number of passenger seats in the vehicle.", "type": "number", "example": 5 }, "transmission": { "description": "Transmission type.", "type": "string", "enum": [ "Manual", "Automatic" ], "example": "Manual" }, "engineSize": { "description": "Engine displacement in cubic centimetres (cc).", "type": "number", "example": 1600 }, "colour": { "description": "Colour of the vehicle.", "type": "string", "example": "Silver" }, "modifications": { "description": "Vehicle modifications.", "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "example": "Roof rack" }, "purchaseDate": { "description": "Date the vehicle was purchased.", "type": "string", "format": "date", "example": "2020-06-15" }, "driveSide": { "description": "Side of the vehicle the steering wheel is located on.", "type": "string", "enum": [ "Left", "Right" ], "example": "Right" }, "usedBy": { "description": "References to persons who use this vehicle.", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" ] } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:UtilityTariff": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:UtilityTariff", "example": "ark:UtilityTariff" }, "utility": { "description": "The type of utility this tariff applies to.", "enum": [ "Gas", "Electricity", "Internet", "Telephone", "Water", "Sewerage", "TV" ], "example": "Electricity" }, "providedBy": { "description": "The organisation that provides this tariff.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "name": { "description": "The name of the tariff or plan.", "type": "string", "example": "Flexible Octopus" }, "fixExpiresOn": { "description": "The date when the fixed-rate period expires, if applicable.", "type": "string", "format": "date", "example": "2027-01-01" }, "fixExitFee": { "description": "The exit fee for leaving the tariff before the fixed period ends, if applicable.", "type": "string", "example": "£30.00" }, "standingCharge": { "description": "The standing charge for the tariff, if applicable.", "type": "string", "example": "£0.20 per day" }, "unitRate": { "description": "The unit rate for the tariff, if applicable.", "type": "string", "example": "15.00p per kWh" } }, "required": [ "id", "type", "utility", "providedBy" ], "additionalProperties": false }, "ark:UtilityProvider": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:UtilityProvider", "example": "ark:UtilityProvider" }, "utility": { "description": "Not in the list? Add council tax, TV licences, boiler maintenance, and similar as bills.", "enum": [ "Gas", "Electricity", "Internet", "Telephone", "Water", "Sewerage", "TV" ] }, "providesTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "providedBy": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "hasAccount": { "description": "If the same company provides multiple utilities (e.g. gas and electricity) and bills them together, you can link them to the same account.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" } }, "required": [ "id", "type", "utility", "providedBy" ], "additionalProperties": false }, "ark:UtilityAccount": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:UtilityAccount", "example": "ark:UtilityAccount" }, "accountNumber": { "description": "You can normally find this on one of your bills.", "type": "string", "minLength": 1, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "accountProvider": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "accountClosedOn": { "description": "Adding a closed date will remove this account from being included in calculations. If you're changing supplier, choose the date when the transfer is complete and all bills are settled.", "type": "string", "format": "date" } }, "required": [ "id", "type", "accountProvider" ], "additionalProperties": false }, "ark:UserProfile": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:UserProfile", "example": "ark:UserProfile" }, "firstName": { "description": "Use the name people use when writing to you, as it helps DataWollet to process documents.", "type": "string", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "lastName": { "type": "string", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "avatar": { "type": "string" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:TransactionPattern": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:TransactionPattern", "example": "ark:TransactionPattern" }, "relatedTo": { "description": "Account the pattern is related to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e568" }, "period": { "description": "The recurrence period for this pattern.", "type": "object", "properties": { "interval": { "description": "The interval type for the pattern.", "type": "string", "enum": [ "MONTH", "WEEK", "QUARTER", "SEMI_ANNUAL", "ANNUAL" ], "example": "MONTH" }, "frequency": { "description": "How often the pattern repeats within the interval (e.g., 1 = every interval, 2 = every other interval).", "type": "integer", "minimum": 1, "example": 1 }, "specifier": { "description": "Additional details about when in the interval the pattern occurs.", "type": "object", "properties": { "dayOfMonth": { "description": "Day of the month the pattern occurs (1-31). Uses 31 for end-of-month patterns.", "type": "integer", "minimum": 1, "maximum": 31, "example": 15 }, "dayOfWeek": { "description": "Day of the week the pattern occurs (0 = Sunday, 1 = Monday, ..., 6 = Saturday).", "type": "integer", "minimum": 0, "maximum": 6, "example": 1 }, "weekOfMonth": { "description": "Week of the month for week-of-month patterns (1-4 for first/second/third/fourth, -1 for last).", "type": "integer", "minimum": -1, "maximum": 4, "example": 1 }, "flexibility": { "description": "How the pattern adjusts for non-working days.", "type": "string", "enum": [ "EXACT", "WORKING_DAY_BEFORE", "WORKING_DAY_AFTER", "NEAREST_WORKING_DAY" ], "example": "WORKING_DAY_BEFORE" } }, "additionalProperties": false } }, "required": [ "interval", "frequency", "specifier" ], "additionalProperties": false }, "commonality": { "description": "Common attributes shared by all transactions in this pattern.", "type": "object", "properties": { "reference": { "description": "Shared reference across all transactions in the pattern.", "type": "string", "example": "SALARY", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "counterparty": { "description": "Shared counterparty name across all transactions in the pattern.", "type": "string", "example": "Netflix", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "merchant": { "description": "Shared merchant ID across all transactions in the pattern.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/organisation/netflix", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "description": { "description": "Shared description across all transactions in the pattern.", "type": "string", "example": "DIRECT DEBIT PAYMENT - NETFLIX", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "category": { "description": "Shared primary category across all transactions in the pattern.", "type": "string", "example": "entertainment", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "methodCategory": { "description": "Shared payment method category across all transactions in the pattern.", "type": "string", "enum": [ "PAYMENT", "PAYMENT:ONLINE", "PAYMENT:DIRECT_DEBIT", "PAYMENT:STANDING_ORDER", "PAYMENT:CARD", "PAYMENT:CARD:CONTACTLESS", "TRANSFER", "TRANSFER:OUT", "TRANSFER:FASTER", "TRANSFER:SAVINGS:OUT", "TRANSFER:SAVINGS:IN", "TRANSFER:P2P", "TRANSFER:CHAPS", "CREDIT", "UNKNOWN" ], "example": "PAYMENT:DIRECT_DEBIT" }, "amount": { "description": "Average amount across all transactions in the pattern, formatted as a decimal string.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{2})?$", "example": "15.99", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "currency": { "description": "Shared currency code across all transactions in the pattern.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "GBP" }, "direction": { "description": "Shared direction (Credit or Debit) across all transactions in the pattern.", "type": "string", "enum": [ "Credit", "Debit" ], "example": "Debit" } }, "additionalProperties": false }, "transactions": { "description": "List of transaction IDs that belong to this pattern.", "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 2, "example": [ "https://graph.datawollet.com/.draft-nodes/tx1", "https://graph.datawollet.com/.draft-nodes/tx2", "https://graph.datawollet.com/.draft-nodes/tx3" ] }, "startDate": { "description": "Date of the first transaction in the pattern.", "type": "string", "format": "date", "example": "2024-01-15" }, "endDate": { "description": "Date of the last transaction in the pattern.", "type": "string", "format": "date", "example": "2024-03-15" }, "nextExpected": { "description": "Predicted dates for the next occurrences of this pattern.", "type": "array", "items": { "type": "string", "format": "date" }, "example": [ "2024-04-15", "2024-05-15", "2024-06-14" ] } }, "required": [ "id", "type", "relatedTo", "period", "commonality", "transactions", "startDate", "endDate", "nextExpected" ], "additionalProperties": false }, "ark:Transaction": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Transaction", "example": "ark:Transaction" }, "sequence": { "description": "This identifier is designed to allow transactions to be sorted to match the data source exactly, by sorting alphanumerically. It is generated using data from the source systems, or for statement sources from the order of the pages and the order within the pages.", "type": "string", "minLength": 1, "example": "20250620001000000001" }, "date": { "description": "Date on which the transaction was booked, or took place if not yet booked.", "type": "string", "format": "date" }, "relatedTo": { "description": "Account the transaction is related to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e568" }, "fullDescriptor": { "description": "Full description of the transaction as it appears on the statement. If no description is provided on the statement, then a single hyphen ('-') is used to indicate no description was available.", "type": "string", "minLength": 1, "example": "B JONES (Faster Payments) Reference: SPOTIFY", "x-policies": { "classification": [ "Personal", "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "description": { "description": "Short description of the transaction, if it was possible to determine.", "type": "string", "example": "B JONES (Faster Payments)", "x-policies": { "classification": [ "Personal", "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "notes": { "description": "Additional details for the transaction that are less important.", "type": "string", "example": "Reference: SPOTIFY", "x-policies": { "classification": [ "Personal", "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "method": { "description": "Method used for the transaction, as described by the bank.", "type": "string", "example": "Faster Payments" }, "reference": { "description": "Reference for the transaction, if available.", "type": "string", "example": "SPOTIFY", "x-policies": { "classification": [ "Personal", "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "methodCategory": { "description": "Category for the method used in the transaction, standardised between banks.", "enum": [ "PAYMENT", "PAYMENT:ONLINE", "PAYMENT:DIRECT_DEBIT", "PAYMENT:STANDING_ORDER", "PAYMENT:CARD", "PAYMENT:CARD:CONTACTLESS", "TRANSFER", "TRANSFER:OUT", "TRANSFER:FASTER", "TRANSFER:SAVINGS:OUT", "TRANSFER:SAVINGS:IN", "TRANSFER:P2P", "TRANSFER:CHAPS", "CREDIT", "UNKNOWN" ], "example": "TRANSFER:FASTER" }, "amount": { "description": "Amount involved in the transaction, including currency.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency", "direction" ], "example": { "type": "ark:Currency", "currency": "GBP", "amount": "5.00", "direction": "Credit" } }, "conversion": { "description": "Original currency and exchange rate, if applicable.", "type": "object", "properties": { "type": { "const": "ark:CurrencyConversion" }, "amount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "description": "Amount of the original transaction currency", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "PSR2017" ] } }, "currency": { "type": "string", "pattern": "^[A-Z\\?]{3}$", "description": "ISO 4217 currency code for the original transaction currency, or '???' if unknown" } }, "required": [ "type" ] }, "rate": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{1,10})?$", "description": "Exchange rate applied to the original transaction currency. Additional fees may apply in addition to the exchange rate, so an exact conversion to the final amount is not certain." } }, "required": [ "type" ], "additionalProperties": false, "example": { "type": "ark:CurrencyConversion", "amount": { "type": "ark:Currency", "currency": "USD", "amount": "6.50" }, "rate": "1.30" } }, "balance": { "description": "Balance associated with the transaction, at the time specified by the balanceAt field. A balance may not be included for all transactions depending on how the bank operates.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "PSR2017" ] } }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency", "direction" ], "example": { "type": "ark:Currency", "currency": "GBP", "amount": "1234.56", "direction": "Credit" } }, "balanceType": { "description": "Treatment of the balance, such as whether it is booked or provisional.", "enum": [ "Booked", "Interim" ], "example": "Booked" }, "balanceAt": { "description": "Whether the balance relates to the opening, interim or closing balance for the period which is normally considered the day of the transaction.", "anyOf": [ { "const": "Opening" }, { "const": "Closing" }, { "const": "Interim" } ], "example": "Closing" }, "counterparty": { "description": "Details for the other party involved in a transaction, which may include a name if available as well as sort code and account number details if provided. When receiving money, this is expected to be the sender, and when sending money this is expected to be the recipient.", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the counterparty, where available.", "x-policies": { "classification": [ "Personal", "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "sortCode": { "type": "string", "pattern": "^[0-9]{2}-[0-9]{2}-[0-9]{2}$", "description": "Sort code of the counterparty's bank, if available." }, "accountNumber": { "type": "string", "pattern": "^[0-9]{7,8}$", "description": "Account number of the counterparty, if available.", "x-policies": { "classification": [ "Personal", "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } } }, "required": [], "example": { "name": "B JONES", "sortCode": "404004", "accountNumber": "12345678" } }, "categories": { "description": "List of categories assigned to the transaction through AI matching. Some transactions are not assigned to categories, for example if there is no known amount.\nThe first item in the list is the primary category, and the second item is a subsidiary of the primary category.\n\nThe current list of **primary** categories is:\n- `travel`\n- `banking`\n- `dependent_costs`\n- `entertainment`\n- `shopping`\n- `food_and_drink`\n- `income`\n- `transport`\n- `media_and_telecoms`\n- `expenses`\n- `insurance`\n- `borrowing_and_loans`\n- `charity`\n- `health_and_personal_care`\n- `home`\n- `taxes`\n- `pensions_savings_and_investments`\n- `education`\n- `gambling_and_lotteries`\n- `mortgage_and_rent`\n- `transfers`\n- `utilities`\n- `general`\n\nThe current list of **subsidiary** categories is:\n- `holiday_and_travel_expenses`\n- `flights_and_airport_expenses`\n- `other_travel`\n- `bank_fees_and_currency_exchange`\n- `other_banking`\n- `cash_withdrawals`\n- `interest`\n- `refunds_and_reversals`\n- `overdraft_fees`\n- `unpaid_transactions`\n- `other_dependent_costs`\n- `child_support`\n- `childcare`\n- `childrens_expenses`\n- `childrens_school_fees`\n- `leisure_and_amusement_activities`\n- `books_and_reading`\n- `cinema`\n- `theatre_concerts_and_tickets`\n- `other_events`\n- `gaming`\n- `sport_events`\n- `other_entertainment`\n- `hobbies`\n- `flowers_and_gifts`\n- `clothing_and_accessories`\n- `department_stores`\n- `electronics_appliances_and_technology`\n- `general_online_shopping`\n- `other_shopping`\n- `smoking_and_vaping`\n- `bars_and_pubs`\n- `coffee`\n- `groceries`\n- `eating_out_and_takeaways`\n- `speciality_food_and_drink`\n- `other_eating_out`\n- `other_food_and_drink`\n- `benefits`\n- `deposits`\n- `other_income`\n- `child_support_income`\n- `crypto_platform_incoming`\n- `rental_income`\n- `investment_income`\n- `employment_income`\n- `pension_income`\n- `public_transport`\n- `petrol_and_vehicle_charging`\n- `parking_and_tolls`\n- `service_stations`\n- `taxi`\n- `vehicle`\n- `vehicle_rental`\n- `other_transport`\n- `broadband`\n- `digital_media_and_software`\n- `mobile`\n- `tv_streaming_services`\n- `tv_licence`\n- `tv_broadband_and_mobile`\n- `other_media_and_telecoms`\n- `business_expenses`\n- `financial_and_legal_expenses`\n- `other_memberships_and_services`\n- `postage_and_office_supplies`\n- `other_expenses`\n- `business_insurance`\n- `home_insurance`\n- `other_insurance`\n- `health_and_life_insurance`\n- `pet_insurance`\n- `travel_insurance`\n- `vehicle_insurance`\n- `buy_now_pay_later`\n- `credit_cards`\n- `debt_management`\n- `loan_incoming`\n- `loan_repayment`\n- `student_loan`\n- `vehicle_loan`\n- `other_borrowing_and_loans`\n- `charity`\n- `other_charity`\n- `healthcare`\n- `beauty`\n- `sport_accessories_and_equipment`\n- `dental`\n- `gym_and_fitness`\n- `pharmacies_and_health_products`\n- `optical`\n- `other_health_and_personal_care`\n- `home_maintenance`\n- `furniture`\n- `gardening`\n- `laundry`\n- `other_home`\n- `household_goods`\n- `pets`\n- `council_tax`\n- `other_taxes`\n- `crypto_platform_outgoing`\n- `investments`\n- `pensions`\n- `savings`\n- `other_pensions_savings_and_investments`\n- `driving_lessons`\n- `other_education`\n- `university_and_tuition`\n- `gambling_and_betting`\n- `lotteries_and_sweepstakes`\n- `other_gambling_and_lotteries`\n- `housing_deposits`\n- `mortgage`\n- `rent`\n- `other_mortgage_and_rent`\n- `internal_transfers`\n- `shared_bills_and_expenses`\n- `transfers_in`\n- `transfers_out`\n- `other_transfers`\n- `utilities_energy`\n- `other_utilities`\n- `utilities_water_and_sewage`\n- `waste_and_recycling`\n- `other_general`\n", "type": "array", "items": { "type": "string" }, "example": [ "travel", "public_transport" ] }, "merchant": { "description": "Merchant associated with the transaction, if it was possible to determine. This matching is performed automatically and may not be accurate, and indicates the merchant was referred to, therefore it may not be the same as the counterparty. The referred node will be an `ark:Organisation` or `ark:Organisation` normally including tags that can be used to infer additional information about the transaction (e.g. gambling providers).", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/organisation/tesco", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "processor": { "description": "Payment processor associated with the transaction, if it was possible to determine. This matching is performed automatically and may not be accurate, and indicates the payment processor was referred to, therefore it may not be the same as the counterparty. The referred node will be an `ark:Organisation` or `ark:Organisation` normally including tags that can be used to infer additional information about the transaction (e.g. BNPL providers) though it should not be taken to indicate the actual nature of the transaction.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/organisation/klarna", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } } }, "required": [ "id", "type", "sequence", "date", "relatedTo", "fullDescriptor", "methodCategory" ], "additionalProperties": false }, "ark:TenancyDeposit": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:TenancyDeposit", "example": "ark:TenancyDeposit" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "identifier": { "description": "This might be called the certificate code or the deposit ID on your protection certificate.", "type": "string", "minLength": 1, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "totalAmount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "collectedOn": { "description": "The date when you paid the deposit.", "type": "string", "format": "date", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "protectedOn": { "description": "The date when the deposit was entered into an approved deposit protection scheme.", "type": "string", "format": "date", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "returnedOn": { "description": "The date when the deposit or part of it was returned to you", "type": "string", "format": "date", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "relatedTo", "identifier", "totalAmount", "protectedOn" ], "additionalProperties": false }, "ark:Tenancy": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Tenancy", "example": "ark:Tenancy" }, "appliesTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "providedBy": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "startedOn": { "description": "The date when you moved in, or the current agreement started.", "type": "string", "format": "date" }, "endedOn": { "description": "You can always change this later. A date in the past will stop DataWollet from considering the costs associated with the tenancy.", "type": "string", "format": "date" } }, "required": [ "id", "type", "appliesTo", "providedBy" ], "additionalProperties": false }, "ark:TaxRecord": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:TaxRecord", "example": "ark:TaxRecord" }, "relatedTo": { "description": "The person to whom this tax record belongs.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "country": { "description": "The country where the tax record applies, using ISO 3166-1 alpha-2 country code.", "type": "string", "pattern": "^[A-Z]{2}$", "example": "GB" }, "scheme": { "description": "The tax or national insurance scheme to which this record applies.", "type": "string", "enum": [ "GB_PAY_AS_YOU_EARN", "GB_NATIONAL_INSURANCE" ], "example": "GB_NATIONAL_INSURANCE" }, "schemeUniqueIdentifier": { "description": "The unique identifier within the specified scheme (e.g., National Insurance number).", "type": "string", "example": "AB123456C", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:TaxCumulation": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:TaxCumulation", "example": "ark:TaxCumulation" }, "relatedTo": { "description": "The tax basis to which this cumulation applies.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "effectiveAt": { "description": "The date at which this tax cumulation is effective.", "type": "string", "format": "date", "example": "2026-01-31" }, "grossPay": { "description": "The cumulative gross pay year-to-date.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "grossPayOfWhichTaxPayable": { "description": "The cumulative taxable pay year-to-date.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "grossPayOfWhichNatInsPayable": { "description": "The cumulative National Insurance pay year-to-date.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "grossPayOfWhichPensionable": { "description": "The cumulative pensionable pay year-to-date.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "taxPaid": { "description": "The cumulative tax paid year-to-date.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "niPaid": { "description": "The cumulative National Insurance contributions paid year-to-date.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:TaxBasis": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:TaxBasis", "example": "ark:TaxBasis" }, "relatedTo": { "description": "The tax record to which this tax basis applies.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "appliesTo": { "description": "The employment to which this tax basis applies.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "scheme": { "description": "The taxation scheme being applied (e.g., GB_PAY_AS_YOU_EARN).", "type": "string", "enum": [ "GB_PAY_AS_YOU_EARN", "GB_NATIONAL_INSURANCE" ], "example": "GB_PAY_AS_YOU_EARN" }, "parameters": { "description": "Scheme-specific parameters such as tax code and NI letter.", "type": "object", "properties": { "taxCode": { "type": "string", "description": "The tax code applicable to this employment.", "pattern": "^[CS]?[0-9]{1,4}[LPTYKMNSX]{0,2}1?" }, "niLetter": { "type": "string", "description": "The National Insurance letter category.", "enum": [ "A", "B", "C", "D", "E", "F", "G", "H", "J", "L", "M", "S", "X", "Z" ] } }, "additionalProperties": true, "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "effectiveAt": { "description": "The date from which this tax basis is effective.", "type": "string", "format": "date", "example": "2026-01-01" } }, "required": [ "id", "type", "relatedTo", "appliesTo" ], "additionalProperties": false }, "ark:Sync": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Sync", "example": "ark:Sync" }, "recipientName": { "description": "The name of the person or organisation you're sharing data with", "type": "string", "minLength": 1 } }, "required": [ "id", "type", "recipientName" ], "additionalProperties": true }, "ark:Suggestion": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Suggestion", "example": "ark:Suggestion" }, "appliesTo": { "description": "The id of the node that this suggestion applies to.", "type": "string", "minLength": 1, "format": "uri", "example": "https://graph.datawollet.com/nodes/76a5512c-9e53-4675-ae5e-759bab13c1e6" }, "comment": { "description": "An explanatory comment associated with the suggestion.", "type": "string", "minLength": 1, "example": "I'll actually only spend £50 on this in future" }, "patch": { "description": "the patch to be applied to the node following the JSON Patch format (RFC 6902).", "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "add", "remove", "replace" ] }, "path": { "type": "string" }, "value": {} }, "required": [ "op", "path" ] } } }, "required": [ "id", "type", "appliesTo" ], "additionalProperties": false }, "ark:Statement": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Statement", "example": "ark:Statement" }, "relatedTo": { "description": "Account that the statement is related to, which may be a bank account or another type of account.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e568" }, "issuedBy": { "description": "Organisation that issued the statement. Normally the same as the organisation that administers the account.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e567" }, "reference": { "description": "Reference identifier for the statement, as assigned by the issuing organisation.", "type": "string", "minLength": 1, "example": "STATEMENT-2024-05-0118735", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "date": { "description": "Date the statement was issued, which may be after the end date of the statement period.", "type": "string", "format": "date", "example": "2024-05-31" }, "startDate": { "description": "Start date of the statement period.", "type": "string", "format": "date", "example": "2024-05-01" }, "endDate": { "description": "End date of the statement period.", "type": "string", "format": "date", "example": "2024-05-31" } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:RegularCharge": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:RegularCharge", "example": "ark:RegularCharge" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "paymentFrequency": { "description": "DataWollet currently only supports a monthly amount, but let us know if you have a different interval.", "anyOf": [ { "const": "Monthly" } ] }, "totalAmount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "name": { "description": "This is optional but can help to explain the detail of what the payment is for. DataWollet sometimes looks for keywords in the name such as 'electricity' to provide more granular insights.", "type": "string", "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "effectiveFrom": { "description": "The date that this rate applies from, useful if the amount increases from time to time.", "type": "string", "format": "date" } }, "required": [ "id", "type", "relatedTo", "paymentFrequency", "totalAmount" ], "additionalProperties": true }, "ark:PropertyValuation": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PropertyValuation", "example": "ark:PropertyValuation" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "date": { "type": "string", "format": "date" }, "value": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "value" ], "additionalProperties": false }, "ark:PropertySecuritySummary": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PropertySecuritySummary", "example": "ark:PropertySecuritySummary" }, "relatedTo": { "description": "The property that this security information describes.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "businessUsage": { "description": "Indicates whether the property is used for business purposes.", "type": "boolean", "example": false }, "businessUsageNonClerical": { "description": "Indicates whether the business use involves non-clerical activities.", "type": "boolean", "example": false }, "businessUsageVisitors": { "description": "Indicates whether business use involves visitors to the property.", "type": "boolean", "example": false }, "locks": { "description": "Information about locks fitted to different parts of the property.", "type": "object", "properties": { "mainDoors": { "type": "string", "description": "Description of locks on main doors." }, "patioDoors": { "type": "string", "description": "Description of locks on patio doors." }, "otherDoors": { "type": "string", "description": "Description of locks on other doors." }, "windows": { "type": "string", "description": "Description of locks on ground floor windows." } }, "additionalProperties": false }, "intruderAlarm": { "description": "Indicates whether the property has an intruder alarm fitted.", "type": "boolean", "example": true }, "intruderAlarmMonitored": { "description": "Indicates whether the intruder alarm is monitored by a security company.", "type": "boolean", "example": false }, "smokeDetectors": { "description": "Indicates whether the property has smoke detectors fitted.", "type": "boolean", "example": true }, "neighbourhoodWatch": { "description": "Indicates whether the property is part of a neighbourhood watch scheme.", "type": "boolean", "example": true }, "normalOccupancy": { "description": "Information about normal occupancy patterns.", "type": "object", "properties": { "day": { "type": "boolean", "description": "Description of whether someone is normally at the property during the day." }, "night": { "type": "boolean", "description": "Description of whether someone is normally at the property during the night." } }, "additionalProperties": false }, "unoccupancy": { "description": "Information about periods when the property is unoccupied.", "type": "object", "properties": { "maximumDays": { "type": "number", "description": "The maximum number of consecutive days the property is left unoccupied." } }, "additionalProperties": false } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:PropertyRiskFactors": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PropertyRiskFactors", "example": "ark:PropertyRiskFactors" }, "relatedTo": { "description": "The property that these risk factors apply to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "heatedBy": { "description": "The primary heating system for the property (e.g., gas central heating, electric heating).", "type": "string", "example": "Gas central heating" }, "listed": { "description": "Indicates whether the property is a listed building.", "type": "boolean", "example": false }, "buildingWorkInProgress": { "description": "Indicates whether there is currently building work in progress at the property.", "type": "boolean", "example": false }, "historyOfFlooding": { "description": "Indicates whether the property has a history of flooding.", "type": "boolean", "example": false }, "historyOfSubsidence": { "description": "Indicates whether the property has a history of subsidence.", "type": "boolean", "example": false }, "historyOfUnderpinning": { "description": "Indicates whether the property has been underpinned.", "type": "boolean", "example": false }, "tallTreesNearby": { "description": "Indicates whether there are tall trees near the property that could pose a risk.", "type": "boolean", "example": false }, "extended": { "description": "Indicates whether the property has been extended.", "type": "boolean", "example": false } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:PropertyOccupancySummary": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PropertyOccupancySummary", "example": "ark:PropertyOccupancySummary" }, "relatedTo": { "description": "The property that this occupancy information describes.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "occupiedAs": { "description": "The current occupancy status of the property (e.g., owner-occupied, rented, vacant).", "type": "string", "example": "Owner-occupied" }, "occupiedSince": { "description": "The date when the current occupancy began.", "type": "string", "format": "date", "example": "2020-06-01" }, "hasMortgage": { "description": "Indicates whether the property has a mortgage.", "type": "boolean", "example": true }, "hasLandlordType": { "description": "The type of landlord if the property is rented (e.g., private, council, housing association).", "type": "string", "example": "Private" }, "hasFurnishings": { "description": "Indicates whether the property is furnished if rented.", "type": "boolean", "example": false }, "hasSmokers": { "description": "Indicates whether there are smokers in the property.", "type": "boolean", "example": false }, "numberOfAdults": { "description": "The number of adults living in the property, or a range (e.g., '>=1', '0').", "type": "string", "example": "2" }, "numberOfChildren": { "description": "The number of children living in the property, or a range (e.g., '>=1', '0').", "type": "string", "example": "1" }, "numberOfPets": { "description": "The number of pets in the property, or a range (e.g., '>=1', '0').", "type": "string", "example": "2" }, "numberOfCats": { "description": "The number of cats in the property, or a range (e.g., '>=1', '0').", "type": "string", "example": "1" }, "numberOfDogs": { "description": "The number of dogs in the property, or a range (e.g., '>=1', '0').", "type": "string", "example": "1" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:PropertyConstruction": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PropertyConstruction", "example": "ark:PropertyConstruction" }, "relatedTo": { "description": "The property that these construction details describe.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "built": { "description": "The year or year range when the property was built (e.g., '1990', '1980-1990').", "type": "string", "example": "1990" }, "roofMaterial": { "description": "The primary material used for the roof (e.g., tiles, slate, thatch).", "type": "string", "example": "Tiles" }, "roofFlatProportion": { "description": "The proportion of the roof that is flat (e.g., '0%', '25%', '50%').", "type": "string", "example": "0%" }, "wallMaterial": { "description": "The primary material used for the walls (e.g., brick, stone, timber).", "type": "string", "example": "Brick" }, "standardConstruction": { "description": "Indicates whether the property is of standard construction (walls and roof made of standard materials).", "type": "boolean", "example": true } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:PropertyCharacteristics": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PropertyCharacteristics", "example": "ark:PropertyCharacteristics" }, "relatedTo": { "description": "The property that these characteristics describe.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "propertyType": { "description": "The type of property (e.g., house, flat, bungalow).", "type": "string", "example": "House" }, "propertySubType": { "description": "The subtype of property (e.g., detached, semi-detached, terraced).", "type": "string", "example": "Detached" }, "numberOfRooms": { "description": "The total number of rooms in the property.", "type": "number", "example": 8 }, "numberOfBedrooms": { "description": "The number of bedrooms in the property.", "type": "number", "example": 3 }, "numberOfBathrooms": { "description": "The number of bathrooms in the property.", "type": "number", "example": 2 }, "numberOfLivingRooms": { "description": "The number of living rooms in the property.", "type": "number", "example": 1 }, "numberOfKitchens": { "description": "The number of kitchens in the property.", "type": "number", "example": 1 }, "numberOfOtherRooms": { "description": "The number of other rooms in the property (e.g., study, utility room).", "type": "number", "example": 1 }, "goodStateOfRepair": { "description": "Indicates whether the property is in a good state of repair.", "type": "boolean", "example": true } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:PropertyBill": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PropertyBill", "example": "ark:PropertyBill" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "issuedBy": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "name": { "type": "string", "minLength": 1 }, "reference": { "type": "string", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "category": { "anyOf": [ { "const": "council-tax" }, { "const": "garden-waste" }, { "const": "parking-permit" }, { "const": "tv-licence" }, { "const": "mobile-phone" }, { "const": "other" } ] } }, "required": [ "id", "type", "relatedTo", "issuedBy", "name", "category" ], "additionalProperties": false }, "ark:Property": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Property", "example": "ark:Property" }, "label": { "description": "The label will appear as the title for your property in the app, so set it to anything you like.", "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "addressLines": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "postcode": { "type": "string", "minLength": 1, "pattern": "^([A-Z][A-HJ-Y]?[0-9O][A-Z0-9]?( )?[0-9O][A-Z]{2}|GIR ?0A{2})$", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "image": { "type": "string" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:Policyholder": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Policyholder", "example": "ark:Policyholder" }, "relatedTo": { "description": "The person who is a policyholder.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "appliesTo": { "description": "The insurance policy or quote that this policyholder is associated with.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "priority": { "description": "The priority level of the policyholder (e.g., Primary or Secondary).", "type": "string", "enum": [ "Primary", "Secondary" ], "example": "Primary" }, "hasUseOfOtherVehicle": { "description": "Indicates whether the policyholder has use of another vehicle.", "type": "boolean", "example": false } }, "required": [ "id", "type", "relatedTo", "appliesTo" ], "additionalProperties": false }, "ark:Person": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Person", "example": "ark:Person" }, "title": { "description": "The person's title, if known and if any.", "type": "string", "example": "Dr" }, "initials": { "description": "The person's initials, if known.", "type": "string", "example": "JD", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "firstName": { "description": "The person's first name, if known.", "type": "string", "example": "John", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "lastName": { "description": "The person's last name, if known.", "type": "string", "example": "Doe", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "knownAs": { "description": "The name the person is has been referred to as, which may be a truncated form of their full legal name. The `ark:Person` node type is intended to be disambiguated when combining data from multiple sources.", "type": "string", "example": "Mr John Doe", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "dateOfBirth": { "description": "The person's date of birth, if known.", "type": "string", "format": "date", "example": "1980-01-01", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "maritalStatus": { "description": "The person's marital status.", "type": "string", "example": "Married" }, "email": { "description": "The person's email address.", "type": "object", "properties": { "primary": { "type": "string", "format": "email", "description": "The person's primary email address.", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "work": { "type": "array", "description": "The person's work email addresses.", "items": { "type": "string", "format": "email", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } } }, "alternate": { "type": "array", "description": "The person's alternate email addresses.", "items": { "type": "string", "format": "email", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } } } } }, "telephone": { "description": "The person's telephone numbers.", "type": "object", "properties": { "primary": { "type": "string", "pattern": "^\\+?[0-9\\s\\-()]{7,20}$", "description": "The person's primary telephone number.", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "home": { "type": "string", "pattern": "^\\+?[0-9\\s\\-()]{7,20}$", "description": "The person's home telephone number.", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "mobile": { "type": "string", "pattern": "^\\+?[0-9\\s\\-()]{7,20}$", "description": "The person's mobile telephone number.", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "work": { "type": "string", "pattern": "^\\+?[0-9\\s\\-()]{7,20}$", "description": "The person's work telephone number.", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } } } }, "occupation": { "description": "The person's occupation.", "type": "object", "properties": { "status": { "type": "string", "description": "The employment status of the person.", "enum": [ "Employed", "Self Employed", "Unemployed", "Retired", "Full-time Education" ] }, "sector": { "type": "string", "description": "The sector of the person's occupation." }, "title": { "type": "string", "description": "The title of the person's occupation.", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } } }, "example": { "status": "Employed", "sector": "Information Technology", "title": "Software Developer" } }, "secondaryOccupation": { "description": "The person's secondary occupation.", "type": "object", "properties": { "status": { "type": "string", "description": "The employment status of the person's secondary occupation.", "enum": [ "Employed", "Self Employed", "Unemployed", "Retired", "Full-time Education" ] }, "sector": { "type": "string", "description": "The sector of the person's secondary occupation." }, "title": { "type": "string", "description": "The title of the person's secondary occupation.", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } } }, "example": { "status": "Employed", "sector": "Healthcare", "title": "Nurse" } } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:Payment": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Payment", "example": "ark:Payment" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "date": { "type": "string", "format": "date" }, "totalAmount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "paymentSource": { "description": "Details of the account and/or person that made the payment.", "type": "string", "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "transactionId": { "type": "string", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "relatedTo", "date", "totalAmount" ], "additionalProperties": true }, "ark:PayPeriod": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PayPeriod", "example": "ark:PayPeriod" }, "relatedTo": { "description": "The employment or contract that this pay period is related to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/employment-contract-1234567890" }, "startDate": { "description": "The start date of the pay period.", "type": "string", "format": "date", "example": "2026-01-01" }, "endDate": { "description": "The end date of the pay period.", "type": "string", "format": "date", "example": "2026-01-31" }, "paymentDate": { "description": "The date the payment was made.", "type": "string", "format": "date", "example": "2026-01-25" }, "grossPay": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "direction": { "type": "string", "description": "Will show as 'Debit' if the amount is negative, such as with refunds.", "enum": [ "Debit" ] } }, "additionalProperties": false, "required": [ "type", "amount" ], "example": { "type": "ark:CurrencyValue", "currency": "GBP", "amount": "2500.58" } }, "taxablePay": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "direction": { "type": "string", "description": "Will show as 'Debit' if the amount is negative, such as with refunds.", "enum": [ "Debit" ] } }, "additionalProperties": false, "required": [ "type", "amount" ], "example": { "type": "ark:CurrencyValue", "currency": "GBP", "amount": "1200.00" } }, "pensionablePay": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "direction": { "type": "string", "description": "Will show as 'Debit' if the amount is negative, such as with refunds.", "enum": [ "Debit" ] } }, "additionalProperties": false, "required": [ "type", "amount" ], "example": { "type": "ark:CurrencyValue", "currency": "GBP", "amount": "800.00" } }, "nonTaxablePay": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "direction": { "type": "string", "description": "Will show as 'Debit' if the amount is negative, such as with refunds.", "enum": [ "Debit" ] } }, "additionalProperties": false, "required": [ "type", "amount" ], "example": { "type": "ark:CurrencyValue", "currency": "GBP", "amount": "1300.58" } }, "totalDeductions": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "direction": { "type": "string", "description": "Will show as 'Debit' if the amount is negative, such as with refunds.", "enum": [ "Debit" ] } }, "additionalProperties": false, "required": [ "type", "amount" ], "example": { "type": "ark:CurrencyValue", "currency": "GBP", "amount": "500.00" } }, "transactions": { "description": "List of transaction IDs that correspond to the salary or other income made during the period.", "type": "array", "items": { "type": "string", "format": "uri" } }, "netPay": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "direction": { "type": "string", "description": "Will show as 'Debit' if the amount is negative, such as with refunds.", "enum": [ "Debit" ] } }, "additionalProperties": false, "required": [ "type", "amount" ], "example": { "type": "ark:CurrencyValue", "currency": "GBP", "amount": "2000.58" } } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:PayItem": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PayItem", "example": "ark:PayItem" }, "relatedTo": { "description": "The pay period to which this pay item belongs.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "description": { "description": "A description of the pay item (e.g., basic salary, overtime, allowance).", "type": "string", "example": "Basic Salary", "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "workAmount": { "description": "The amount worked or earned (e.g., hours worked, units earned).", "type": "number", "example": 160 }, "payAmount": { "description": "The amount paid for this item (e.g., hours paid).", "type": "number", "example": 160 }, "rateAmount": { "description": "The rate at which this pay item is calculated (e.g., hourly rate).", "type": "number", "example": 15.5, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "totalAmount": { "description": "The total amount for this pay item.", "type": "object", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] }, "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:PayDeduction": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PayDeduction", "example": "ark:PayDeduction" }, "relatedTo": { "description": "The pay period to which this deduction belongs.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "description": { "description": "A description of the deduction (e.g., income tax, National Insurance, pension contribution).", "type": "string", "example": "Income Tax", "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "totalAmount": { "description": "The total amount deducted. Credit direction indicates a refund.", "type": "object", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] }, "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:PayBasis": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:PayBasis", "example": "ark:PayBasis" }, "relatedTo": { "description": "The employment to which this pay basis applies.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "appliesTo": { "description": "The pay period to which this pay basis applies.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "providedBy": { "description": "The organisation that provides or administers this pay scale.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "name": { "description": "The name of the pay scale or pay basis (e.g., pay band, grade).", "type": "string", "example": "Band 5", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "effectiveAt": { "description": "The date from which this pay basis is effective.", "type": "string", "format": "date", "example": "2026-01-01" }, "incrementAt": { "description": "The date when the next pay increment is due.", "type": "string", "format": "date", "example": "2027-04-01" } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:Passport": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Passport", "example": "ark:Passport" }, "passportNumber": { "description": "The unique passport number.", "type": "string", "example": "123456789", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "passportType": { "description": "The type of passport.", "type": "string", "example": "P" }, "passportCode": { "description": "The ISO 3166-1 alpha-3 country code of the issuing country.", "type": "string", "pattern": "^[A-Z]{3}$", "example": "GBR" }, "surname": { "description": "The surname as it appears on the passport.", "type": "string", "example": "DOE", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "givenName": { "description": "The given name(s) as they appear on the passport.", "type": "string", "example": "JOHN ALEXANDER", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "dateOfBirth": { "description": "The date of birth of the passport holder.", "type": "string", "format": "date", "example": "1990-01-01", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "sex": { "description": "The sex of the passport holder as indicated on the passport.", "type": "string", "example": "M", "enum": [ "M", "F", "X" ] }, "expiresAt": { "description": "The date when the passport expires.", "type": "string", "format": "date", "example": "2032-10-12", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "issuedAt": { "description": "The date when the passport was issued.", "type": "string", "format": "date", "example": "2022-10-12", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "issuingAuthority": { "description": "The authority that issued the passport.", "type": "string", "example": "HMPO" }, "nationality": { "description": "The nationality of the passport holder.", "type": "string", "example": "BRITISH CITIZEN" }, "placeOfBirth": { "description": "The place of birth of the passport holder.", "type": "string", "example": "CARDIFF", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "issuedBy": { "description": "The organisation that issued the passport.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/cf5066ba5267e1b74d6dd0a23ee673b6" }, "relatedTo": { "description": "The person that the passport is related to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/cf5066ba5267e1b74d6dd0a23ee673b6" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:Organisation": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Organisation", "example": "ark:Organisation" }, "name": { "type": "string", "minLength": 1 }, "companyRegistrationNumber": { "description": "You don't need to add a company number, but DataWollet can use them to help distinguish between companies with similar names.", "type": "string", "pattern": "^(([A-Z]{2})[0-9]{6}|R[0-9]{7}|RC[0-9]{1,}|[0-9]{3,8})$" }, "fcaRegisterNumber": { "description": "Most UK banks, finance organisations, and insurers will have an entry on the Financial Conduct Authority register.", "type": "string", "pattern": "^[0-9]{6,7}$" }, "companyDomains": { "description": "These are parts of web and email addresses (after the @) that DataWollet can in some circumstances use to identify correspondence from an organisation. It may not be the same as the domain(s) used for their marketing and website.", "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^(?!www\\.)((?!-))(xn--)?[a-z0-9][a-z0-9-_]{0,61}[a-z0-9]{0,1}\\.(xn--)?([a-z0-9\\-]{1,61}|[a-z0-9-]{1,30}\\.[a-z]{2,})$" }, "example": [ "example.com", "example.org" ] }, "website": { "description": "The main website for the organisation.", "type": "string", "example": "https://www.example.com" }, "logo": { "description": "A URI that resolves to a logo for the organisation.", "type": "string", "format": "uri", "example": "https://www.example.com/logo.png" }, "slug": { "description": "A short, human-readable identifier for the organisation, which may be used in URLs. If not provided, one will be generated from the name.", "type": "string", "example": "example-bank" }, "tags": { "description": "Tags can be used to help categorise and group organisations.", "type": "array", "items": { "type": "string", "minLength": 1 }, "example": [ "bank", "uk" ] } }, "required": [ "id", "type", "name" ], "additionalProperties": true }, "ark:MortgagePaymentPlan": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:MortgagePaymentPlan", "example": "ark:MortgagePaymentPlan" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "loanAmount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "repaymentMethod": { "anyOf": [ { "const": "Interest only" }, { "const": "Capital and interest" } ] } }, "required": [ "id", "type", "relatedTo", "loanAmount", "repaymentMethod" ], "additionalProperties": false }, "ark:MortgageIllustration": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:MortgageIllustration", "example": "ark:MortgageIllustration" }, "label": { "description": "This label is only used to help you distinguish between different illustrations issued by the same provider.", "type": "string", "minLength": 1 }, "issuedBy": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "producedOn": { "description": "The date the illustration was produced.", "type": "string", "format": "date" } }, "required": [ "id", "type", "label", "issuedBy" ], "additionalProperties": true }, "ark:MortgageAccount": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:MortgageAccount", "example": "ark:MortgageAccount" }, "accountNumber": { "description": "You can normally find this on a statement or welcome letter.", "type": "string", "minLength": 1, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "accountProvider": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "appliesTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "illustration": { "description": "The illustration contains details on the payments and interest rates. Adding the document to DataWollet will speed everything up, but we can estimate using a statement if you don't have one.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "startedOn": { "description": "We'll start calculating interest from this date.", "type": "string", "format": "date" }, "endedOn": { "description": "Adding a settled date will remove this account from being included in calculations. If you're remortgaging, set the date once your old mortgage provider has received the money for the balance.", "type": "string", "format": "date" } }, "required": [ "id", "type", "accountNumber", "accountProvider", "appliesTo" ], "additionalProperties": false }, "ark:Licence": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Licence", "example": "ark:Licence" }, "licenceNumber": { "description": "The unique licence number.", "type": "string", "example": "DOE9905010JD1XX78", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "licenceType": { "description": "The type of licence.", "type": "string", "example": "Driving" }, "issuedBy": { "description": "The organisation that issued the licence.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/9fa913c1b7cea4e08823c43cc87caaa" }, "relatedTo": { "description": "The person that the licence is related to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/cf5066ba5267e1b74d6dd0a23ee673b6" }, "issuingAuthority": { "description": "The authority that issued the licence.", "type": "string", "example": "DVLA" }, "issuedAt": { "description": "The date when the licence was issued.", "type": "string", "format": "date", "example": "2025-01-01", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "expiresAt": { "description": "The date when the licence expires.", "type": "string", "format": "date", "example": "2035-01-01", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:InterestRate": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:InterestRate", "example": "ark:InterestRate" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "determination": { "anyOf": [ { "const": "Fixed" }, { "const": "Standard Variable" }, { "const": "Variable Tracker" } ] }, "rate": { "description": "Enter the current rate, but be aware that a rate that isn't fixed could change in the future.", "type": "string", "minLength": 1, "pattern": "^[1-9]?[0-9](\\.[0-9]{1,10})?%$" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveUntil": { "description": "If you're on a fixed rate for a few years, enter the end date of your fix so we can remind you.", "type": "string", "format": "date" } }, "required": [ "id", "type", "relatedTo", "determination", "rate" ], "additionalProperties": true }, "ark:InsuranceQuote": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:InsuranceQuote", "example": "ark:InsuranceQuote" }, "relatedTo": { "description": "The asset that this insurance quote covers (e.g., property, vehicle).", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "quoteNumber": { "description": "The unique identifier for this insurance quote.", "type": "string", "example": "QTE123456789", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "startDate": { "description": "The proposed start date for the insurance coverage.", "type": "string", "format": "date", "example": "2026-01-01" }, "endDate": { "description": "The proposed end date for the insurance coverage.", "type": "string", "format": "date", "example": "2027-01-01" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:InsurancePolicy": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:InsurancePolicy", "example": "ark:InsurancePolicy" }, "relatedTo": { "description": "The asset that this insurance policy covers (e.g., property, vehicle).", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "policyNumber": { "description": "The unique identifier for this insurance policy.", "type": "string", "example": "POL123456789", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "startDate": { "description": "The date when the insurance policy begins.", "type": "string", "format": "date", "example": "2026-01-01" }, "endDate": { "description": "The date when the insurance policy expires.", "type": "string", "format": "date", "example": "2027-01-01" }, "renewalDate": { "description": "The date when the insurance policy is due for renewal.", "type": "string", "format": "date", "example": "2027-01-01" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:InsuranceCoverage": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:InsuranceCoverage", "example": "ark:InsuranceCoverage" }, "relatedTo": { "description": "The insurance policy or quote that this coverage applies to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "coverage": { "description": "The name or type of coverage provided.", "type": "string", "example": "Buildings" }, "coversBuildings": { "description": "Indicates whether this coverage includes buildings insurance.", "type": "boolean", "example": true }, "coversContents": { "description": "Indicates whether this coverage includes personal possessions, away from home (for property) or inside the vehicle (for vehicle).", "type": "boolean", "example": true }, "coversAccidents": { "description": "Indicates whether this coverage includes accidental damage.", "type": "boolean", "example": true }, "coversEmergency": { "description": "Indicates whether this coverage includes emergency assistance.", "type": "boolean", "example": true }, "coversLegal": { "description": "Indicates whether this coverage includes legal protection.", "type": "boolean", "example": true }, "coversPossessions": { "description": "Indicates whether this coverage includes personal belongings or possessions.", "type": "boolean", "example": true }, "coversVehicleDamage": { "description": "Indicates whether this coverage includes loss or damage of the vehicle.", "type": "boolean", "example": true }, "coversPersonalAccident": { "description": "Indicates whether this coverage includes personal accident protection.", "type": "boolean", "example": true }, "coversWindscreen": { "description": "Indicates whether this coverage includes windscreen and window damage.", "type": "boolean", "example": true }, "coversVehicleThirdParty": { "description": "Indicates whether this coverage includes third party liability for the vehicle.", "type": "boolean", "example": true }, "coversVehicleFireTheft": { "description": "Indicates whether this coverage includes fire and theft protection for the vehicle.", "type": "boolean", "example": true }, "yearsWithoutClaims": { "description": "The number of years without claims for this type of coverage.", "type": "number", "example": 5 }, "limitations": { "description": "Limitations or restrictions on the coverage.", "type": "object", "properties": { "classOfUse": { "description": "The class of use for vehicle insurance coverage.", "type": "string", "enum": [ "Social, domestic & pleasure", "Social, domestic, pleasure & commuting", "Social, domestic, pleasure, commuting & business" ] }, "annualMileage": { "description": "The estimated annual mileage for vehicle insurance coverage.", "type": "number", "example": 10000 }, "hazardousGoods": { "description": "Indicates whether vehicle is used for transporting hazardous goods.", "type": "boolean", "example": false }, "signWriting": { "description": "Indicates whether vehicle has graphics (e.g. text, logos, branding) applied to its exterior.", "type": "boolean", "example": false } }, "additionalProperties": true }, "rebuildCost": { "description": "The estimated cost to rebuild the property.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "restockCost": { "description": "The estimated cost to replace contents.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "coversDrivers": { "description": "References to persons who are named drivers on the policy.", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" ] } }, "required": [ "id", "type", "coverage" ], "additionalProperties": false }, "ark:InstalmentSchedule": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:InstalmentSchedule", "example": "ark:InstalmentSchedule" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "paymentScheduleSequence": { "type": "integer" }, "payment": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "paymentCount": { "type": "integer", "minimum": 1 } }, "required": [ "id", "type", "relatedTo", "paymentScheduleSequence", "payment", "paymentCount" ], "additionalProperties": false }, "ark:InstalmentCount": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:InstalmentCount", "example": "ark:InstalmentCount" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "paymentFrequency": { "description": "DataWollet currently only supports a monthly amount, but let us know if you have a different interval.", "anyOf": [ { "const": "Monthly" } ] }, "paymentCount": { "description": "If DataWollet doesn't have a full schedule of exact payments, the total number of payments can be used to estimate your monthly payments instead.", "type": "integer", "minimum": 1 } }, "required": [ "id", "type", "relatedTo", "paymentFrequency" ], "additionalProperties": false }, "ark:Instalment": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Instalment", "example": "ark:Instalment" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "date": { "type": "string", "format": "date" }, "totalAmount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "relatedTo", "date", "totalAmount" ], "additionalProperties": false }, "ark:IncomePattern": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:IncomePattern", "example": "ark:IncomePattern" }, "reason": { "description": "Identifier used to group patterns together.", "enum": [ "INCOME", "BORROWING", "ESSENTIAL", "QUALITY_OF_LIFE" ], "example": "INCOME" }, "description": { "description": "A human-readable description of the pattern.", "type": "string", "example": "Net Pay" }, "relatedTo": { "description": "The budget that this income pattern relates to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/nodes/f85b8b6b37fe3e8b144829d200000000" }, "group": { "description": "The category of the income pattern.", "type": "string", "example": "income" }, "total": { "description": "Total monthly amount for this income category, formatted as a decimal string.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{2})?$", "example": "2500.00", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "items": { "description": "The individual income components: either transaction patterns (URIs) or averaged transactions from a category that didn't match a pattern.", "type": "array", "items": { "anyOf": [ { "title": "IncomePatternReference", "description": "Reference to a TransactionPattern node representing recurring income.", "type": "object", "properties": { "id": { "description": "URI of the TransactionPattern node that defines the recurring pattern.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/pattern123" }, "amount": { "description": "The monthly amount for this pattern, formatted as a decimal string.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{2})?$", "example": "150.00", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } } }, "required": [ "id", "amount" ], "additionalProperties": false }, { "title": "IncomeAggregatedTransactions", "description": "Aggregated transactions from a category that didn't match a pattern.", "type": "object", "properties": { "amount": { "description": "Average amount per period (monthly average) across all transactions, formatted as a decimal string.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{2})?$", "example": "150.00", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "transactions": { "description": "Array of transaction IDs that make up this aggregated group.", "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "example": [ "https://graph.datawollet.com/.draft-nodes/tx1", "https://graph.datawollet.com/.draft-nodes/tx2" ] } }, "required": [ "description", "amount", "transactions" ], "additionalProperties": false } ] } } }, "required": [ "id", "type", "reason", "description", "total", "items", "relatedTo" ], "additionalProperties": false }, "ark:ExpenditurePattern": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:ExpenditurePattern", "example": "ark:ExpenditurePattern" }, "reason": { "description": "Identifier used to group patterns together.", "enum": [ "BORROWING", "ESSENTIAL", "QUALITY_OF_LIFE" ], "example": "ESSENTIAL" }, "relatedTo": { "description": "The budget that this expenditure pattern relates to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/nodes/f85b8b6b37fe3e8b144829d200000000" }, "description": { "description": "A human-readable description of the pattern.", "type": "string", "example": "Mortgages" }, "group": { "description": "The group of the expenditure pattern.", "type": "string", "example": "mortgage" }, "total": { "description": "Total monthly amount for this expenditure category, formatted as a decimal string.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{2})?$", "example": "1250.00", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "items": { "description": "The individual expenditure components: either transaction patterns (URIs) or averaged transactions from a category that didn't match a pattern.", "type": "array", "items": { "anyOf": [ { "title": "ExpenditurePatternReference", "description": "Reference to a TransactionPattern node representing recurring expenditure.", "type": "object", "properties": { "id": { "description": "URI of the TransactionPattern node that defines the recurring pattern.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/pattern123" }, "amount": { "description": "The monthly amount for this pattern, formatted as a decimal string.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{2})?$", "example": "150.00", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } } }, "required": [ "id", "amount" ], "additionalProperties": false }, { "title": "ExpenditureAggregatedTransactions", "description": "Aggregated transactions from a category that didn't match a pattern.", "type": "object", "properties": { "amount": { "description": "Average amount per period (monthly average) across all transactions, formatted as a decimal string.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{2})?$", "example": "45.99", "x-policies": { "classification": [ "Financial", "Sensitive" ], "regulations": [ "GDPR", "PSR2017" ] } }, "transactions": { "description": "Array of transaction IDs that make up this aggregated group.", "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "example": [ "https://graph.datawollet.com/.draft-nodes/tx1", "https://graph.datawollet.com/.draft-nodes/tx2" ] } }, "required": [ "amount", "transactions" ], "additionalProperties": false } ] } } }, "required": [ "id", "type", "reason", "description", "group", "total", "items", "relatedTo" ], "additionalProperties": false }, "ark:Entitlement": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Entitlement", "example": "ark:Entitlement" }, "providedBy": { "description": "The licence or document that provides this entitlement.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/c57ae0606463ff569bb600191954aaaa" }, "activity": { "description": "The activity that the entitlement permits.", "type": "string", "example": "Driving" }, "geography": { "description": "The geographical area where the entitlement is valid.", "type": "string", "example": "United Kingdom" }, "addedDate": { "description": "The date the entitlement was obtained/added or the test was passed.", "type": "string", "format": "date", "example": "2015-06-20" }, "limitations": { "description": "Limitations or restrictions on the entitlement.", "type": "object", "properties": { "vehicleClassCodes": { "description": "Vehicle class codes that the entitlement covers.", "type": "array", "items": { "type": "string" }, "example": [ "AM", "A", "B1", "B", "BE", "f", "k", "p", "q" ] }, "isProvisional": { "description": "Indicates whether this entitlement is provisional.", "type": "boolean", "example": false } }, "additionalProperties": true } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:Employment": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Employment", "example": "ark:Employment" }, "employee": { "description": "The person associated with the employment.", "type": "string", "example": "https://graph.noah.myark.io/.draft-nodes/2df392d18d21c02b11bdb966457cb930" }, "employer": { "description": "The organisation associated with the employment.", "type": "string", "example": "https://graph.noah.myark.io/.draft-nodes/2df392d18d21c02b11bdb966457cb930" }, "jobTitle": { "description": "The job title associated with the employment.", "type": "string", "example": "Software Engineer", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "department": { "description": "The department associated with the employment.", "type": "string", "example": "Engineering", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "reference": { "description": "The reference number associated with the employment.", "type": "string", "example": "12345889", "x-policies": { "classification": "PII", "regulations": [ "GDPR" ] } }, "payFrequency": { "description": "The frequency at which the employee is paid.", "type": "string", "example": "Monthly", "enum": [ "Weekly", "Fortnightly", "Four-weekly", "Monthly", "Quarterly", "Semi-annual", "Annual" ] }, "effectiveAt": { "description": "The date the employment became effective.", "type": "string", "format": "date", "example": "2020-01-01" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:CreditAccount": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "pattern": "^https://[a-z0-9.\\-]+(myark\\.io|datawollet\\.com)/", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:CreditAccount", "example": "ark:CreditAccount" }, "accountType": { "description": "The type of credit account.", "enum": [ "CreditCard" ], "example": "CreditCard" }, "issuedBy": { "description": "Organisation that issued or administers the account.", "type": "string", "pattern": "^https://[a-z0-9.\\-]+(myark\\.io|datawollet\\.com)/", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e567" } }, "required": [ "id", "type" ], "additionalProperties": false }, "ark:Credit": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Credit", "example": "ark:Credit" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "date": { "type": "string", "format": "date" }, "totalAmount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "name": { "description": "This is optional but can help to explain the detail, such as if it's a direct debit payment or a refund.", "type": "string", "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "reason": { "description": "Only payments will be included in your outgoings. If you don't select a reason, DataWollet will normally assume it's a payment.", "anyOf": [ { "const": "Payment" }, { "const": "Refund" }, { "const": "Adjustment" }, { "const": "Discount" }, { "const": "Negative" }, { "const": "Other" } ] } }, "required": [ "id", "type", "relatedTo", "date", "totalAmount" ], "additionalProperties": true }, "ark:Charge": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Charge", "example": "ark:Charge" }, "relatedTo": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "date": { "type": "string", "format": "date" }, "totalAmount": { "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false, "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "name": { "description": "This is optional but can help to explain the detail, such as if it's an interest charge or the service provided.", "type": "string", "x-policies": { "classification": "Sensitive", "regulations": [ "GDPR" ] } }, "periodStart": { "type": "string", "format": "date" }, "periodEnd": { "description": "If the charge relates to a specific time period, like for utilities, then adding these dates can improve the accuracy of our estimates.", "type": "string", "format": "date" } }, "required": [ "id", "type", "relatedTo", "totalAmount" ], "additionalProperties": true, "anyOf": [ { "required": [ "date" ] }, { "required": [ "periodStart" ] }, { "required": [ "periodEnd" ] } ] }, "ark:Budget": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Budget", "example": "ark:Budget" }, "includes": { "description": "The account IDs that this budget was derived from.", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "https://graph.datawollet.com/nodes/account1", "https://graph.datawollet.com/nodes/account2" ] }, "startDate": { "description": "The earliest date of the transactions analysed to produce this budget.", "type": "string", "format": "date", "example": "2024-01-01" }, "endDate": { "description": "The latest date of the transactions analysed to produce this budget.", "type": "string", "format": "date", "example": "2024-06-30" } }, "required": [ "id", "type", "includes", "startDate", "endDate" ], "additionalProperties": false }, "ark:Bill": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Bill", "example": "ark:Bill" }, "relatedTo": { "description": "The property bill or account that this bill relates to.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "issuedBy": { "description": "The organisation that issued this bill.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "issuedOn": { "description": "The date when the bill was issued.", "type": "string", "format": "date", "example": "2026-01-15" }, "reference": { "description": "The reference number or account number for this bill.", "type": "string", "example": "CT123456789", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "relatedTo", "issuedBy" ], "additionalProperties": false }, "ark:BankAccountIdentifier": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:BankAccountIdentifier", "example": "ark:BankAccountIdentifier" }, "identifierType": { "description": "The type of account identifier, using a controlled vocabulary.\n", "enum": [ "IBAN", "SORT_CODE_ACCOUNT_NUMBER", "LABEL" ], "example": "SORT_CODE_ACCOUNT_NUMBER" }, "identifier": { "description": "Identifier for the bank account, which will conform to the type specified.", "type": "string", "example": "00-00-00 00000123", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "relatedTo": { "description": "Bank account associated with the identifier.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e567" } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:BankAccountHolder": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:BankAccountHolder", "example": "ark:BankAccountHolder" }, "appliesTo": { "description": "Account that the person holds.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e568" }, "relatedTo": { "description": "Person that is the account holder.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e123" } }, "required": [ "id", "type", "appliesTo", "relatedTo" ], "additionalProperties": false }, "ark:BankAccount": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:BankAccount", "example": "ark:BankAccount" }, "accountType": { "description": "The type of account where this is known, using a controlled vocabulary.\nDataWollet currently only officially supports current accounts, but more will follow.\n", "enum": [ "Current", "Savings" ], "example": "Current" }, "productName": { "description": "Brand name for the product associated with the bank account, where known.", "type": "string", "example": "Everyday Saver" }, "issuedBy": { "description": "Organisation that issued or administers the account.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e567" } }, "required": [ "id", "type", "issuedBy" ], "additionalProperties": false }, "ark:Balance": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Balance", "example": "ark:Balance" }, "onAccount": { "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "date": { "type": "string", "format": "date" }, "totalAmount": { "description": "Your account is in credit if you've overpaid or paid for more than you've used so far. Your account is in debit if you owe the lender money.", "type": "object", "properties": { "type": { "const": "ark:CurrencyValue" }, "amount": { "type": "string", "pattern": "^[0-9]{1,}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "direction": { "type": "string", "enum": [ "Credit", "Debit" ] } }, "required": [ "amount", "currency", "direction" ], "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "position": { "description": "If set to an opening balance, any charges or credits on the same day will be applied after this balance. A closing balance is at the end of the period, so the end of the day after all charges and credits were applied.", "anyOf": [ { "const": "Opening" }, { "const": "Closing" } ] } }, "required": [ "id", "type", "onAccount", "date", "totalAmount" ], "additionalProperties": false }, "ark:Address": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:Address", "example": "ark:Address" }, "addressLines": { "description": "The lines of the address, excluding the postcode.", "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "example": [ "123 Example Street", "Example Town" ], "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } }, "postcode": { "description": "The postcode for this address.", "type": "string", "minLength": 1, "pattern": "^([A-Z][A-HJ-Y]?[0-9O][A-Z0-9]?( )?[0-9O][A-Z]{2}|GIR ?0A{2})$", "example": "SW1A 1AA", "x-policies": { "classification": "Linkable", "regulations": [ "GDPR" ] } } }, "required": [ "id", "type", "addressLines", "postcode" ], "additionalProperties": false }, "ark:AccountIdentifier": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:AccountIdentifier", "example": "ark:AccountIdentifier" }, "identifierType": { "description": "The type of account identifier, using a controlled vocabulary.\n", "enum": [ "IBAN", "SORT_CODE_ACCOUNT_NUMBER", "LABEL", "PAN" ], "example": "SORT_CODE_ACCOUNT_NUMBER" }, "identifier": { "description": "Identifier for the account, which will conform to the type specified.", "type": "string", "example": "00-00-00 00000123", "x-policies": { "classification": "Financial", "regulations": [ "GDPR" ] } }, "relatedTo": { "description": "Account associated with the identifier.", "type": "string", "format": "uri", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e567" } }, "required": [ "id", "type", "relatedTo" ], "additionalProperties": false }, "ark:AccountHolder": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "description": "URI format identifier used to refer to this node within the graph.", "type": "string", "pattern": "^https://[a-z0-9.\\-]+(myark\\.io|datawollet\\.com)/", "example": "https://graph.datawollet.com/.draft-nodes/f85b8b6b37fe3e8b144829d200000000" }, "relationship": { "description": "The nature of the relationship between the account holder and the account.", "enum": [ "Primary", "Secondary" ], "example": "Primary" }, "type": { "description": "A type identifier used to indicate the data model that the node conforms to.", "type": "string", "const": "ark:AccountHolder", "example": "ark:AccountHolder" }, "appliesTo": { "description": "Account that the person holds.", "type": "string", "pattern": "^https://[a-z0-9.\\-]+(myark\\.io|datawollet\\.com)/", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e568" }, "relatedTo": { "description": "Person that is the account holder.", "type": "string", "pattern": "^https://[a-z0-9.\\-]+(myark\\.io|datawollet\\.com)/", "example": "https://graph.datawollet.com/.draft-nodes/0118735d359276fd42741493c449e123" } }, "required": [ "id", "type", "appliesTo", "relatedTo" ], "additionalProperties": false } } }, "paths": { "/ais": { "get": { "summary": "Retrieve list of available AIS providers and institutions", "operationId": "getAis", "description": "\n This endpoint retrieves a list of available Account Information Service Providers (AISPs) and their associated institutions that can be connected to via\n DataWollet's Open Finance platform.\n\n DataWollet can facilitate connections using its hosted Open Finance platform, or clients can use their own AIS provider if they hold the necessary\n regulatory permissions.\n\n **This endpoint is not generally available and must be activated on request.**\n ", "tags": [ "ais" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "List of available AIS providers and institutions", "content": { "application/json": { "schema": { "type": "array", "description": "List of available AIS connection options", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Underlying AIS provider", "example": "moneyhub-live" }, "id": { "type": "string", "description": "Identifier for the connection option", "example": "barclays" }, "displayName": { "type": "string", "description": "Display name for the connection option", "example": "Barclays" }, "organisationNames": { "type": "array", "description": "List of organisation names associated with the connection option", "items": { "type": "string" } }, "logoUri": { "type": "string", "description": "URI for the logo of the connection option", "example": "https://cdn.example.com/barclays-logo.png", "x-format": { "uri": true } }, "customerType": { "type": "array", "description": "Types of customers supported by this connection option", "items": { "type": "string", "enum": [ "Personal", "Business" ] } }, "accountType": { "type": "array", "description": "Types of accounts supported by this connection option", "items": { "type": "string", "enum": [ "Savings", "Current", "Credit card" ] } }, "options": { "type": "array", "description": "List of specific options available", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for the specific option within the connection", "example": "mh-barclays-personal" }, "href": { "type": "string", "description": "URI associated with the specific option", "example": "https://api.datawollet.com/ais/mh-barclays-personal", "x-format": { "uri": true } }, "displayName": { "type": "string", "description": "Display name for the specific option", "example": "Barclays Personal" }, "providerId": { "type": "string", "description": "Identifier assigned by the underlying AIS provider to this option", "example": "barclays-personal" } }, "required": [ "id", "href", "displayName", "providerId" ] } } }, "required": [ "provider", "id", "displayName", "logoUri" ] } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have the ais:initiate scope" }, "500": { "description": "Failed to retrieve connection options from AIS provider" } } }, "post": { "summary": "Confirm open banking connection", "operationId": "postAis", "description": "\n This endpoint is used to confirm an open banking connection after the user has authenticated with their bank and authorised the connection. It retrieves an\n access token from the AIS provider which can then be used to retrieve banking data. Data should be fetched directly from the AIS provider using their APIs,\n rather than retrieved from the session as part of the security model.\n\n DataWollet's hosted Open Finance solution manages the standardisation of data to match documentary-evidence such as bank statements.\n\n **This endpoint is not generally available and must be activated on request.**\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to associate the connection with" }, "description": "Session ID to associate the connection with" } ], "tags": [ "ais" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Authorisation code returned during redirection to the client" }, "token": { "type": "string", "description": "Token returned during redirection to the client" }, "sessionId": { "type": "string", "description": "Session ID" }, "provider": { "type": "string", "description": "Underlying AIS provider used for the connection, your own provider may be used if the regulatory approvals are held", "enum": [ "moneyhub-sandbox", "moneyhub-live" ] }, "state": { "type": "string", "description": "State to determine redirect URI" } }, "required": [ "code", "token", "provider", "state" ] } } } }, "responses": { "200": { "description": "Access token for AIS resource server API calls", "content": { "application/json": { "schema": { "type": "object", "description": "Response returned when confirming an AISP connection", "properties": { "tokens": { "type": "object", "description": "Tokens returned from the AIS provider", "properties": { "accessToken": { "type": "string", "description": "Access token to be used for subsequent API calls, which are made directly to the AIS provider" } }, "required": [ "accessToken" ] } } } } } }, "400": { "description": "Missing session ID, authorisation code, or token" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have the ais:initiate scope, or session key verification failed" }, "500": { "description": "Failed to retrieve access token from the AIS provider" } } } }, "/envelope": { "get": { "summary": "Get envelope information", "operationId": "getEnvelope", "description": "Returns metadata about the envelope attached to the current session, including its owner, status, and creation date.", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string" }, "required": true } ], "tags": [ "envelope" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Envelope info", "content": { "application/json": { "schema": { "type": "object", "properties": { "envelopeId": { "type": "string", "description": "Unique envelope identifier", "example": "envelope_abc123def456ghi789jk" }, "ownerClientId": { "type": "string", "description": "Client ID of the envelope owner", "example": "qzfpenwbykaptwqapn" }, "status": { "type": "string", "description": "Current envelope status", "example": "active", "enum": [ "active", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the envelope was created", "example": "2024-01-15T10:30:00.000Z" }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "envelopeId", "ownerClientId", "status", "createdAt", "links" ] } } } }, "403": { "description": "Authentication failed, session key invalid, envelope inactive, or no ACL entry for this client" }, "412": { "description": "Session is not attached to an envelope" } } } }, "/storage": { "get": { "summary": "Get pre-signed URLs for persistent storage", "operationId": "getStorage", "description": "\n Returns pre-signed URLs (GET and PUT) for persistent storage tied to user sessions, or the\n signed-in user.\n\n The storage is either session-specific, or user-specific depending on whether or not a guest\n session is in use.\n\n The returned URLs expire at the same time as the session, ensuring that storage access is\n tied to the session lifecycle.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID for which to generate storage URLs" }, "description": "Session ID for which to generate storage URLs", "required": true } ], "tags": [ "storage" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Pre-signed URLs generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "getUrl": { "type": "string", "description": "Pre-signed GET URL for retrieving persistent storage", "example": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..." }, "putUrl": { "type": "string", "description": "Pre-signed PUT URL for uploading persistent storage", "example": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..." }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the URLs will expire", "example": "2024-01-15T11:30:00.000Z" }, "links": { "type": "object", "description": "Links for this storage resource", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "expiresAt" ] } } } }, "400": { "description": "Missing session-id header or invalid credentials" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Session key verification failed, or client does not have wallet:read or wallet:write scope" }, "422": { "description": "Session not found, expired, or terminated" }, "500": { "description": "Failed to generate pre-signed storage URLs" } } } }, "/envelope/acl": { "get": { "summary": "Get envelope ACL entries", "operationId": "getEnvelopeAcl", "description": "Returns all access control entries for the envelope. Each entry shows a client (and optionally a subject) that has been granted access, along with the grant type and timestamp.", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string" }, "required": true } ], "tags": [ "envelope" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Envelope ACL", "content": { "application/json": { "schema": { "type": "object", "properties": { "envelopeId": { "type": "string", "description": "Envelope this ACL belongs to", "example": "envelope_abc123def456ghi789jk" }, "acl": { "type": "array", "description": "List of access control entries", "items": { "type": "object", "properties": { "clientId": { "type": "string", "description": "Client ID granted access", "example": "qzfpenwbykaptwqapn" }, "subId": { "type": "string", "description": "Subject ID for public client grants", "example": "user-12345" }, "grantType": { "type": "string", "description": "How access was granted", "example": "client", "enum": [ "client", "sub", "ticket" ] }, "grantedAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when access was granted", "example": "2024-01-15T10:30:00.000Z" }, "links": { "type": "object", "properties": { "delete": { "type": "string", "description": "URI to revoke this ACL entry", "example": "https://api.datawollet.com/envelope/acl/qzfpenwbykaptwqapn", "x-format": { "uri": true } } }, "required": [ "delete" ] } }, "required": [ "clientId", "grantType", "grantedAt" ] } }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "envelopeId", "acl", "links" ] } } } }, "403": { "description": "Authentication failed, session key invalid, envelope inactive, or no ACL entry for this client" }, "412": { "description": "Session is not attached to an envelope" } } }, "post": { "summary": "Grant access to envelope", "operationId": "postEnvelopeAcl", "description": "\n Grants a target client access to this envelope.\n \n For confidential clients, a direct client grant is created. For public clients without a subId,\n a ticket-based grant is created if the target client has a ticket template configured. The grant\n type determines how the target client attaches to the envelope in future sessions.\n\n Note that clients need to be configured before they can be granted access through ACLs, either with\n template URLs for ticket-based methods, or with key-exchange methods for direct grants. This endpoint\n will reject grant requests that cannot be fulfilled based on the target client's configuration.\n\n Speak to DataWollet support if you need to set up client configurations or have questions about\n options for sharing data between different organisations, M2M clients, or user-centric applications -\n all of these use cases are supported through the envelope mechanisms but require different approaches\n to client configuration and ACL management.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string" }, "required": true } ], "tags": [ "envelope" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "description": "Target client ID or alias", "example": "qzfpenwbykaptwqapn" }, "subId": { "type": "string", "description": "Target subject ID for public client grants", "example": "user-12345" } }, "required": [ "clientId" ] } } } }, "responses": { "200": { "description": "Access granted", "content": { "application/json": { "schema": { "type": "object", "properties": { "grantType": { "type": "string", "description": "Type of grant that was created", "example": "client", "enum": [ "client", "sub", "ticket" ] }, "ticketUri": { "type": "string", "description": "Ticket URI for ticket-based grants, to be shared with the target client", "example": "https://api.datawollet.com/session/start?ticket=ticket_abc123", "x-format": { "uri": true } }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "grantType", "links" ] } } } }, "403": { "description": "Authentication failed, session key invalid, envelope inactive, encryption key unavailable, or no ACL entry for caller" }, "404": { "description": "Target client ID or alias not found in the client registry" }, "409": { "description": "ACL entry already exists for this client, or envelope was modified concurrently — retry the request" }, "412": { "description": "Session is not attached to an envelope" }, "422": { "description": "Invalid grant configuration — subId cannot be set for confidential clients, public client has no ticket template and no subId, or grant type not yet supported (client/sub grants require key exchange configuration)" } } } }, "/envelope/audit": { "get": { "summary": "Get envelope audit log", "operationId": "getEnvelopeAudit", "description": "Returns a paginated list of audit events for the envelope, including ACL grants, revocations, and session attachments/detachments.", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string" }, "required": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "tags": [ "envelope" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Audit events", "content": { "application/json": { "schema": { "type": "object", "properties": { "envelopeId": { "type": "string", "description": "Envelope this audit log belongs to", "example": "envelope_abc123def456ghi789jk" }, "events": { "type": "array", "description": "List of audit events", "items": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Unique audit event identifier", "example": "2024-01-15T10:30:00.000Z-granted-a1b2c3" }, "eventType": { "type": "string", "description": "Type of audit event", "example": "datawollet:audit:envelope:aclGranted" }, "clientId": { "type": "string", "description": "Client that performed the action", "example": "qzfpenwbykaptwqapn" }, "subId": { "type": "string", "description": "Subject ID if action was performed by a public client user", "example": "user-12345" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the event occurred", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "eventId", "eventType", "clientId", "createdAt" ] } }, "nextCursor": { "type": "string", "description": "Cursor for the next page, or null if no more events", "example": null, "nullable": true }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "URI for the current page", "example": "https://api.datawollet.com/envelope/audit?limit=25", "x-format": { "uri": true } }, "next": { "type": "string", "description": "URI for the next page of results", "example": null, "nullable": true, "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "envelopeId", "events", "nextCursor", "links" ] } } } }, "403": { "description": "Authentication failed, session key invalid, envelope inactive, or no ACL entry for this client" }, "412": { "description": "Session is not attached to an envelope" } } } }, "/graph/sources": { "get": { "summary": "List sources in the session wallet", "operationId": "getGraphSources", "description": "\n Returns a paginated list of sources in the session wallet. Each source represents\n a document that was extracted and added to the session.\n\n The list view excludes the full nodes array to reduce payload size. Use the\n individual source endpoint to retrieve full node data for a specific source.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to retrieve sources from" }, "description": "Session ID to retrieve sources from", "required": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Number of sources to return", "default": 25, "minimum": 1, "maximum": 100 }, "description": "Number of sources to return" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination, based on the order items were added" }, "description": "Cursor for pagination, based on the order items were added" } ], "tags": [ "graph" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Sources retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "description": "List of extraction sources in the wallet", "items": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this extraction request", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "sessionId": { "type": "string", "description": "Session ID this extraction is associated with, or null for standalone requests", "example": "sess_abc123", "nullable": true }, "addedAt": { "type": "string", "description": "ISO8601 timestamp when this source was added to the session wallet", "example": "2024-01-15T10:30:00.000Z", "x-format": { "isoDate": true } }, "clientDescription": { "type": "object", "description": "Client authentication and billing context", "properties": { "clientId": { "type": "string", "description": "Unique identifier for the API client", "example": "qzfpenwbykaptwqapn" }, "tenantId": { "type": "string", "description": "Tenant organisation identifier", "example": "your-org" }, "subjectId": { "type": "string", "description": "Subject identifier for the authenticated user, if using user-level authentication", "example": "user-12345", "nullable": true } }, "required": [ "clientId", "tenantId" ] }, "inputs": { "type": "array", "description": "List of input documents processed in this extraction", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Original filename of the uploaded document, or `unknown` if not provided", "example": "counciltax.pdf" }, "mimeType": { "type": "string", "description": "MIME type of the input document", "example": "application/pdf", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "sizeInBytes": { "type": "number", "description": "Size of the uploaded document in bytes", "example": 4121589 }, "checksum": { "type": "string", "description": "SHA-256 checksum of the uploaded file content", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } }, "required": [ "filename", "mimeType", "sizeInBytes" ] } }, "result": { "type": "object", "properties": { "status": { "type": "object", "description": "Status information for the extraction operation", "properties": { "extraction": { "type": "string", "description": "Status of the extraction process. Synchronous endpoints always return COMPLETE or an error.", "enum": [ "COMPLETE" ] }, "review": { "type": "string", "description": "Indicates whether manual review is recommended. REVIEW_PENDING suggests low confidence, fallback profile usage, or unsatisfied required expectations.", "enum": [ "REVIEW_PENDING", "REVIEW_NOT_REQUIRED" ] }, "expectations": { "type": "object", "description": "Summary of expectation rule evaluations against extracted data", "properties": { "errors": { "type": "array", "description": "Unsatisfied required expectations and schema validation failures", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "warnings": { "type": "array", "description": "Unsatisfied recommended expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "info": { "type": "array", "description": "Unsatisfied optional expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } } }, "required": [ "errors", "warnings", "info" ] } }, "required": [ "extraction", "review", "expectations" ] }, "document": { "type": "object", "properties": { "classIdentifier": { "type": "string", "description": "Machine-readable identifier for the document class, or null if classification failed", "example": "property-council-tax-bill", "nullable": true }, "className": { "type": "string", "description": "Human-readable name of the document class", "example": "Property: Council tax bill" }, "classConfidence": { "type": "number", "description": "Confidence score for the document classification (0-100)", "example": 95, "minimum": 0, "maximum": 100 }, "profilesMatched": { "type": "array", "description": "List of extraction profiles that were applied to this document", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the extraction profile", "example": "bill-council-tax-generic" }, "title": { "type": "string", "description": "Human-readable title of the extraction profile", "example": "Generic council tax bill" }, "version": { "type": "string", "description": "Semantic version of the extraction profile", "example": "1.0.0" } } } } }, "required": [ "className", "classConfidence", "profilesMatched" ] }, "text": { "type": "object", "properties": { "source": { "type": "string", "description": "How text was extracted: Embedded (from PDF), OCR (image recognition), or Mixed (combination)", "enum": [ "Embedded", "OCR", "Mixed" ] }, "content": { "type": "string", "description": "Full text content extracted from all pages of the document", "example": "COUNCIL TAX BILL..." } }, "required": [ "source", "content" ] }, "nodeCount": { "type": "number", "description": "Number of nodes extracted from this document", "example": 42 } }, "required": [ "status", "document", "text", "nodeCount" ] }, "links": { "type": "object", "description": "Links for this source", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "requestId", "addedAt", "clientDescription", "inputs" ] } }, "nextCursor": { "type": "string", "description": "Cursor for fetching the next page, or null if no more results", "example": null, "nullable": true }, "total": { "type": "number", "description": "Total number of sources in the session wallet", "example": 5 }, "links": { "type": "object", "description": "HATEOAS links for pagination", "properties": { "self": { "type": "string", "description": "Canonical URI for this collection", "example": "https://api.datawollet.com/graph/sources", "x-format": { "uri": true } }, "next": { "type": "string", "description": "URI for the next page of results, or null if no more pages", "example": "https://api.datawollet.com/graph/sources?cursor=abc&limit=25", "nullable": true, "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "sources", "nextCursor", "total" ] } } } }, "400": { "description": "Missing or invalid session-id header" }, "403": { "description": "Session key verification failed, missing sessions:read scope, or envelope access requires envelopes:read scope" } } } }, "/identity/vouchsafe": { "get": { "summary": "Get identity verification nodes for a session", "operationId": "getIdentityVouchsafe", "description": "\n Retrieves identity verification nodes associated with the specified session.\n\n The endpoint fetches verification data from the external identity provider for all\n verification IDs stored in the session, transforms the data into graph nodes, and\n returns them to the client.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to retrieve verification nodes for" }, "description": "Session ID to retrieve verification nodes for", "required": true } ], "tags": [ "identity" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Verification nodes retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "description": "List of identity verification results for the session", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID associated with the verification", "example": "vrf_abc123" }, "status": { "type": "string", "description": "Status of the verification", "example": "completed" }, "url": { "type": "string", "description": "The verification URL for a user to resume a pending verification", "example": "https://verify.example.com/v/abc123", "x-format": { "uri": true } }, "result": { "type": "object", "properties": { "nodes": { "type": "array", "description": "Nodes extracted from the data verified by the identity verification process", "items": { "type": "object" } } }, "required": [ "nodes" ] } }, "required": [ "id", "status", "url", "result" ] } } } } }, "400": { "description": "Missing session-id header or invalid credentials" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have the identity:initiate scope, or session key verification failed" }, "500": { "description": "Failed to retrieve verification data from the identity provider" } } }, "post": { "summary": "Request identity verification for a session", "operationId": "postIdentityVouchsafe", "description": "\n Initiates an identity verification flow for the specified session using an external identity provider.\n\n The endpoint generates a verification URL that the user should be redirected to in order to complete\n the identity verification process. The verification details are stored in the session for later retrieval.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to associate the verification with, if not supplied in the payload" }, "description": "Session ID to associate the verification with, if not supplied in the payload", "required": true } ], "tags": [ "identity" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID to associate with the verification request" }, "email": { "type": "string", "description": "Email address of the user to verify", "x-format": { "email": true } }, "redirectUrl": { "type": "string", "description": "Optional URL to redirect to after verification", "x-format": { "uri": true } } }, "required": [ "id", "email" ] } } } }, "responses": { "200": { "description": "Verification request created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The verification URL to redirect the user to", "example": "https://verify.example.com/v/abc123", "x-format": { "uri": true } }, "id": { "type": "string", "description": "The verification ID for tracking purposes", "example": "vrf_abc123" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the verification link expires", "example": "2024-01-15T11:30:00.000Z" } }, "required": [ "url", "id", "expiresAt" ] } } } }, "400": { "description": "Missing session-id header, invalid email, or invalid credentials" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have the identity:initiate scope, or session key verification failed" }, "500": { "description": "Failed to create verification request with the identity provider" } } } }, "/settings/portals": { "get": { "summary": "List portals for the authenticated tenant", "operationId": "getSettingsPortals", "description": "\n Returns a paginated list of portals associated with the authenticated tenant.\n Each portal represents a white-labeled front-end configuration with branding information.\n ", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Number of portals to return", "default": 25, "minimum": 1, "maximum": 100 }, "description": "Number of portals to return" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "description": "Cursor for pagination" } ], "tags": [ "settings" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Portals retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "portals": { "type": "array", "description": "List of portal summaries", "items": { "type": "object", "properties": { "portalId": { "type": "string", "description": "Portal ID with prefix and 22-char base64url suffix", "pattern": "^portal_[A-Za-z0-9_-]{22}$" }, "slug": { "type": "string", "description": "URL-safe slug for the portal", "minLength": 3, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "logoUri": { "type": "string", "description": "Logo URL", "nullable": true, "x-format": { "uri": true } }, "links": { "type": "object", "description": "Links for this portal", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "portalId", "slug" ] } }, "nextCursor": { "type": "string", "description": "Cursor for next page of results", "example": null, "nullable": true }, "total": { "type": "integer", "description": "Total number of portals", "example": 3 }, "links": { "type": "object", "description": "Links for the collection", "properties": { "self": { "type": "string", "description": "Canonical URI for this collection", "example": "https://api.datawollet.com/graph/sources", "x-format": { "uri": true } }, "next": { "type": "string", "description": "URI for the next page of results, or null if no more pages", "example": "https://api.datawollet.com/graph/sources?cursor=abc&limit=25", "nullable": true, "x-format": { "uri": true } } }, "required": [ "self" ] } } } } } }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have the settings:read scope" } } } }, "/graph/sources/{requestId}": { "get": { "summary": "Get a specific source with full node data", "operationId": "getGraphSourcesRequestid", "description": "\n Returns the full source data including all extracted nodes for a specific document\n in the session wallet.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to retrieve source from" }, "description": "Session ID to retrieve source from", "required": true }, { "name": "requestId", "in": "path", "schema": { "type": "string", "description": "Request ID of the source to retrieve" }, "description": "Request ID of the source to retrieve", "required": true } ], "tags": [ "graph" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Source retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this extraction request", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "sessionId": { "type": "string", "description": "Session ID this extraction is associated with, or null for standalone requests", "example": "sess_abc123", "nullable": true }, "addedAt": { "type": "string", "description": "ISO8601 timestamp when this source was added to the session wallet", "example": "2024-01-15T10:30:00.000Z", "x-format": { "isoDate": true } }, "clientDescription": { "type": "object", "description": "Client authentication and billing context", "properties": { "clientId": { "type": "string", "description": "Unique identifier for the API client", "example": "qzfpenwbykaptwqapn" }, "tenantId": { "type": "string", "description": "Tenant organisation identifier", "example": "your-org" }, "subjectId": { "type": "string", "description": "Subject identifier for the authenticated user, if using user-level authentication", "example": "user-12345", "nullable": true } }, "required": [ "clientId", "tenantId" ] }, "inputs": { "type": "array", "description": "List of input documents processed in this extraction", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Original filename of the uploaded document, or `unknown` if not provided", "example": "counciltax.pdf" }, "mimeType": { "type": "string", "description": "MIME type of the input document", "example": "application/pdf", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "sizeInBytes": { "type": "number", "description": "Size of the uploaded document in bytes", "example": 4121589 }, "checksum": { "type": "string", "description": "SHA-256 checksum of the uploaded file content", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } }, "required": [ "filename", "mimeType", "sizeInBytes" ] } }, "result": { "type": "object", "properties": { "status": { "type": "object", "description": "Status information for the extraction operation", "properties": { "extraction": { "type": "string", "description": "Status of the extraction process. Synchronous endpoints always return COMPLETE or an error.", "enum": [ "COMPLETE" ] }, "review": { "type": "string", "description": "Indicates whether manual review is recommended. REVIEW_PENDING suggests low confidence, fallback profile usage, or unsatisfied required expectations.", "enum": [ "REVIEW_PENDING", "REVIEW_NOT_REQUIRED" ] }, "expectations": { "type": "object", "description": "Summary of expectation rule evaluations against extracted data", "properties": { "errors": { "type": "array", "description": "Unsatisfied required expectations and schema validation failures", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "warnings": { "type": "array", "description": "Unsatisfied recommended expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "info": { "type": "array", "description": "Unsatisfied optional expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } } }, "required": [ "errors", "warnings", "info" ] } }, "required": [ "extraction", "review", "expectations" ] }, "document": { "type": "object", "properties": { "classIdentifier": { "type": "string", "description": "Machine-readable identifier for the document class, or null if classification failed", "example": "property-council-tax-bill", "nullable": true }, "className": { "type": "string", "description": "Human-readable name of the document class", "example": "Property: Council tax bill" }, "classConfidence": { "type": "number", "description": "Confidence score for the document classification (0-100)", "example": 95, "minimum": 0, "maximum": 100 }, "profilesMatched": { "type": "array", "description": "List of extraction profiles that were applied to this document", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the extraction profile", "example": "bill-council-tax-generic" }, "title": { "type": "string", "description": "Human-readable title of the extraction profile", "example": "Generic council tax bill" }, "version": { "type": "string", "description": "Semantic version of the extraction profile", "example": "1.0.0" } } } } }, "required": [ "className", "classConfidence", "profilesMatched" ] }, "text": { "type": "object", "properties": { "source": { "type": "string", "description": "How text was extracted: Embedded (from PDF), OCR (image recognition), or Mixed (combination)", "enum": [ "Embedded", "OCR", "Mixed" ] }, "content": { "type": "string", "description": "Full text content extracted from all pages of the document", "example": "COUNCIL TAX BILL..." } }, "required": [ "source", "content" ] }, "nodes": { "type": "array", "description": "Array of extracted data nodes forming a directed graph. Each node has a `type` property (prefixed with `ark:`) and a unique `id`. Node types include transactions, accounts, addresses, people, etc.", "items": { "type": "object" } } }, "required": [ "status", "document", "text", "nodes" ] }, "links": { "type": "object", "description": "Links for this source", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/graph/sources/a1b2c3d4", "x-format": { "uri": true } }, "collection": { "type": "string", "description": "URI for the parent collection", "example": "https://api.datawollet.com/graph/sources", "x-format": { "uri": true } }, "via": { "type": "array", "description": "URIs for source files that can be downloaded if file retention is enabled", "items": { "type": "string", "x-format": { "uri": true } } } }, "required": [ "self" ] } }, "required": [ "requestId", "addedAt", "clientDescription", "inputs" ] } } } }, "400": { "description": "Missing or invalid session-id header or requestId parameter" }, "403": { "description": "Session key verification failed, missing sessions:read scope, or envelope access requires envelopes:read scope" }, "404": { "description": "Source with the given requestId not found in session wallet" }, "410": { "description": "Session data is no longer available — encryption key has expired" } } } }, "/settings/portals/{slug}": { "get": { "summary": "Get portal configuration by slug", "operationId": "getSettingsPortalsSlug", "description": "\n Returns the portal configuration for a specific portal by its slug.\n This endpoint allows anonymous access so front-ends can load portal styling\n before user authentication.\n ", "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string", "description": "Portal slug", "minLength": 3, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "Portal slug", "required": true } ], "tags": [ "settings" ], "responses": { "200": { "description": "Portal retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "portalId": { "type": "string", "description": "Portal ID with prefix and 22-char base64url suffix", "example": "portal_abc123def456ghi789jk", "pattern": "^portal_[A-Za-z0-9_-]{22}$" }, "slug": { "type": "string", "description": "URL-safe slug for the portal", "example": "my-portal", "minLength": 3, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "tenantId": { "type": "string", "description": "Associated tenant ID", "example": "your-org" }, "logoUri": { "type": "string", "description": "Logo URL", "example": "https://cdn.example.com/logo.png", "nullable": true, "x-format": { "uri": true } }, "stylesheetUris": { "type": "array", "description": "Array of stylesheet URLs", "items": { "type": "string", "x-format": { "uri": true } } }, "createdAt": { "type": "string", "description": "ISO timestamp when portal was created", "example": "2024-01-15T10:30:00.000Z", "x-format": { "isoDate": true } }, "updatedAt": { "type": "string", "description": "ISO timestamp when portal was last updated", "example": "2024-01-16T08:00:00.000Z", "x-format": { "isoDate": true } }, "links": { "type": "object", "description": "Links for this portal", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "portalId", "slug", "tenantId", "createdAt", "updatedAt" ] } } } }, "404": { "description": "No portal found with the specified slug" } } } }, "/graph/sources/{requestId}/files/{checksum}": { "get": { "summary": "Download a retained source file", "operationId": "getGraphSourcesRequestidFilesChecksum", "description": "\n Downloads a retained source file by its checksum. File retention must be enabled for the\n client and the file must exist in the session wallet.\n\n Files are stored with an expiration date based on the client's retention settings.\n Once expired, files will return a 404 response.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to retrieve file from" }, "description": "Session ID to retrieve file from", "required": true }, { "name": "requestId", "in": "path", "schema": { "type": "string", "description": "Request ID of the source" }, "description": "Request ID of the source", "required": true }, { "name": "checksum", "in": "path", "schema": { "type": "string", "description": "SHA-256 checksum of the file" }, "description": "SHA-256 checksum of the file", "required": true } ], "tags": [ "graph" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "File downloaded successfully", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Missing or invalid session-id header, requestId, or checksum parameter" }, "403": { "description": "Session key verification failed, missing documents:read scope, or envelope access requires envelopes:read scope" }, "404": { "description": "File retention not enabled, source not found in session, checksum not in source inputs, or file has expired" }, "410": { "description": "File data is no longer available — encryption key has expired" } } } }, "/ais/{optionId}": { "post": { "summary": "Initiate an open banking connection", "operationId": "postAisOptionid", "description": "\n This endpoint is used to initiate a new connection to an open banking provider, which is associated with an existing session. It is used as part of\n DataWollet's Open Finance platform whereby banking data can be supplied either as bank statements or through direct connections to the user's bank\n via an Account Information Service Provider (AIS) Provider.\n\n AIS is a regulated activity in the United Kingdom and European Union, and as such clients wishing to use this functionality must hold the appropriate\n regulatory permissions.\n\n DataWollet can facilitate connections using its hosted Open Finance platform, or clients can use their own AIS provider if they hold the necessary\n regulatory permissions.\n\n **This endpoint is not generally available and must be activated on request.**\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to associate the connection with, if not supplied in the payload" }, "description": "Session ID to associate the connection with, if not supplied in the payload" }, { "name": "optionId", "in": "path", "schema": { "type": "string", "description": "Identifier for the connection option to start, returned from the options endpoint" }, "description": "Identifier for the connection option to start, returned from the options endpoint", "required": true } ], "tags": [ "ais" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "nullable": true, "properties": { "sessionId": { "type": "string", "description": "Session ID the events are associated with, if not supplied as a header" }, "state": { "type": "string", "description": "Opaque state value used to determine the redirect URI after bank authentication" } }, "required": [ "state" ] } } } }, "responses": { "200": { "description": "Redirect URI to authenticate the open banking connection", "content": { "application/json": { "schema": { "type": "object", "description": "Response returned when initiating an AISP connection", "properties": { "redirectUri": { "type": "string", "description": "URI to redirect the user to, to authenticate the open banking connection", "example": "https://bank.example.com/authorize?client_id=...", "x-format": { "uri": true } } }, "required": [ "redirectUri" ] } } } }, "400": { "description": "Missing session ID or connection option ID" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have the ais:initiate scope, or session key verification failed" }, "404": { "description": "Connection option with the specified optionId not found" }, "500": { "description": "Failed to initiate connection with the AIS provider" } } } }, "/documents/append": { "post": { "summary": "Append document extraction to a session", "operationId": "postDocumentsAppend", "description": "\n Used to extract data from a document and append the results to an existing session. The session ID must be supplied as a header because of the payload format,\n and the session must be valid and not expired.\n\n This endpoint has similar behaviour to the singular document extraction endpoint, but associates the extracted data with the specified session.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to append the document extraction to" }, "description": "Session ID to append the document extraction to", "required": true } ], "tags": [ "documents" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "description": "Single PDF or image (PNG/JPG) file under 4.5 MB", "example": "document.pdf", "x-meta": { "swaggerType": "file" }, "format": "binary" }, "uploadId": { "type": "string", "description": "Unique upload identifier returned from POST /documents/upload", "example": "upload_AbCdEfGhIjKlMnO", "pattern": "^upload_[A-Za-z0-9_-]+$" }, "filename": { "type": "string", "description": "Original filename of the uploaded document (used with uploadId). Defaults to unknown if omitted.", "example": "statement.pdf", "maxLength": 255 } } } }, "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "string", "description": "Single PDF or image (PNG/JPG) file under 4.5 MB", "example": "document.pdf", "x-meta": { "swaggerType": "file" }, "format": "binary" }, "uploadId": { "type": "string", "description": "Unique upload identifier returned from POST /documents/upload", "example": "upload_AbCdEfGhIjKlMnO", "pattern": "^upload_[A-Za-z0-9_-]+$" }, "filename": { "type": "string", "description": "Original filename of the uploaded document (used with uploadId). Defaults to unknown if omitted.", "example": "statement.pdf", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Document extraction completed without error", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this extraction request", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "clientDescription": { "type": "object", "description": "Client authentication and billing context", "properties": { "clientId": { "type": "string", "description": "Unique identifier for the API client", "example": "qzfpenwbykaptwqapn" }, "tenantId": { "type": "string", "description": "Tenant organisation identifier", "example": "your-org" }, "subjectId": { "type": "string", "description": "Subject identifier for the authenticated user, if using user-level authentication", "example": "user-12345", "nullable": true } }, "required": [ "clientId", "tenantId" ] }, "inputs": { "type": "array", "description": "List of input documents processed in this extraction", "x-constraint": { "length": 1 }, "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Original filename of the uploaded document, or `unknown` if not provided", "example": "counciltax.pdf" }, "mimeType": { "type": "string", "description": "MIME type of the input document", "example": "application/pdf", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "sizeInBytes": { "type": "number", "description": "Size of the uploaded document in bytes", "example": 4121589 }, "checksum": { "type": "string", "description": "SHA-256 checksum of the uploaded file content", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } }, "required": [ "filename", "mimeType", "sizeInBytes" ] } }, "result": { "type": "object", "properties": { "status": { "type": "object", "description": "Status information for the extraction operation", "properties": { "extraction": { "type": "string", "description": "Status of the extraction process. Synchronous endpoints always return COMPLETE or an error.", "enum": [ "COMPLETE" ] }, "review": { "type": "string", "description": "Indicates whether manual review is recommended. REVIEW_PENDING suggests low confidence, fallback profile usage, or unsatisfied required expectations.", "enum": [ "REVIEW_PENDING", "REVIEW_NOT_REQUIRED" ] }, "expectations": { "type": "object", "description": "Summary of expectation rule evaluations against extracted data", "properties": { "errors": { "type": "array", "description": "Unsatisfied required expectations and schema validation failures", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "warnings": { "type": "array", "description": "Unsatisfied recommended expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "info": { "type": "array", "description": "Unsatisfied optional expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } } }, "required": [ "errors", "warnings", "info" ] } }, "required": [ "extraction", "review", "expectations" ] }, "document": { "type": "object", "properties": { "classIdentifier": { "type": "string", "description": "Machine-readable identifier for the document class, or null if classification failed", "example": "property-council-tax-bill", "nullable": true }, "className": { "type": "string", "description": "Human-readable name of the document class", "example": "Property: Council tax bill" }, "classConfidence": { "type": "number", "description": "Confidence score for the document classification (0-100)", "example": 95, "minimum": 0, "maximum": 100 }, "profilesMatched": { "type": "array", "description": "List of extraction profiles that were applied to this document", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the extraction profile", "example": "bill-council-tax-generic" }, "title": { "type": "string", "description": "Human-readable title of the extraction profile", "example": "Generic council tax bill" }, "version": { "type": "string", "description": "Semantic version of the extraction profile", "example": "1.0.0" } } } } }, "required": [ "className", "classConfidence", "profilesMatched" ] }, "text": { "type": "object", "properties": { "source": { "type": "string", "description": "How text was extracted: Embedded (from PDF), OCR (image recognition), or Mixed (combination)", "enum": [ "Embedded", "OCR", "Mixed" ] }, "content": { "type": "string", "description": "Full text content extracted from all pages of the document", "example": "COUNCIL TAX BILL..." } }, "required": [ "source", "content" ] }, "nodes": { "type": "array", "description": "Array of extracted data nodes forming a directed graph. Each node has a `type` property (prefixed with `ark:`) and a unique `id`. Node types include transactions, accounts, addresses, people, etc.", "items": { "type": "object" } } }, "required": [ "status", "document", "text", "nodes" ] }, "links": { "type": "object", "description": "Links for this document extraction", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "requestId", "clientDescription", "inputs" ] } } } }, "400": { "description": "Invalid file type (not PDF/JPEG/PNG), missing document field, or payload exceeds 4.5 MB" }, "500": { "description": "OCR processing failure, document classification error, or extraction pipeline error" } } } }, "/documents/single": { "post": { "summary": "Extract data from single input", "operationId": "postDocumentsSingle", "description": "\n Receives a single file input and attempts to both classify the document, to identify its type, and then extract structured data from it. Structured data is presented\n as a collection of nodes that are inter-related (a directed acylic graph), with the relationships between nodes described using the URIs of another node as property values.\n\n Ensure either a content type or file extension is supplied with the form data. A PDF with no content or an image type will use machine learning to identify text and its bounding\n boxes before classifiation and extraction. A PDF with text content will use this content directly, and will be slightly faster.\n\n The returned nodes vary depending on the type of document and data within.\n\n This endpoint is synchronous and will return a response within roughly ten seconds for most documents. For multi-page image capture or long PDFs, an extraction session should\n be used instead as this allows for background processing while new pages are being captured.\n\n The payload must contain exactly one of `document` (multipart/form-data file upload) or `uploadId` (JSON reference to a\n previously created upload via POST /documents/upload). The `filename` field is only used with `uploadId`.\n ", "tags": [ "documents" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "description": "Single PDF or image (PNG/JPG) file under 4.5 MB", "example": "document.pdf", "x-meta": { "swaggerType": "file" }, "format": "binary" }, "uploadId": { "type": "string", "description": "Unique upload identifier returned from POST /documents/upload", "example": "upload_AbCdEfGhIjKlMnO", "pattern": "^upload_[A-Za-z0-9_-]+$" }, "filename": { "type": "string", "description": "Original filename of the uploaded document (used with uploadId). Defaults to unknown if omitted.", "example": "statement.pdf", "maxLength": 255 } } } }, "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "string", "description": "Single PDF or image (PNG/JPG) file under 4.5 MB", "example": "document.pdf", "x-meta": { "swaggerType": "file" }, "format": "binary" }, "uploadId": { "type": "string", "description": "Unique upload identifier returned from POST /documents/upload", "example": "upload_AbCdEfGhIjKlMnO", "pattern": "^upload_[A-Za-z0-9_-]+$" }, "filename": { "type": "string", "description": "Original filename of the uploaded document (used with uploadId). Defaults to unknown if omitted.", "example": "statement.pdf", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Document extraction completed without error", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this extraction request", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "clientDescription": { "type": "object", "description": "Client authentication and billing context", "properties": { "clientId": { "type": "string", "description": "Unique identifier for the API client", "example": "qzfpenwbykaptwqapn" }, "tenantId": { "type": "string", "description": "Tenant organisation identifier", "example": "your-org" }, "subjectId": { "type": "string", "description": "Subject identifier for the authenticated user, if using user-level authentication", "example": "user-12345", "nullable": true } }, "required": [ "clientId", "tenantId" ] }, "inputs": { "type": "array", "description": "List of input documents processed in this extraction", "x-constraint": { "length": 1 }, "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Original filename of the uploaded document, or `unknown` if not provided", "example": "counciltax.pdf" }, "mimeType": { "type": "string", "description": "MIME type of the input document", "example": "application/pdf", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "sizeInBytes": { "type": "number", "description": "Size of the uploaded document in bytes", "example": 4121589 }, "checksum": { "type": "string", "description": "SHA-256 checksum of the uploaded file content", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } }, "required": [ "filename", "mimeType", "sizeInBytes" ] } }, "result": { "type": "object", "properties": { "status": { "type": "object", "description": "Status information for the extraction operation", "properties": { "extraction": { "type": "string", "description": "Status of the extraction process. Synchronous endpoints always return COMPLETE or an error.", "enum": [ "COMPLETE" ] }, "review": { "type": "string", "description": "Indicates whether manual review is recommended. REVIEW_PENDING suggests low confidence, fallback profile usage, or unsatisfied required expectations.", "enum": [ "REVIEW_PENDING", "REVIEW_NOT_REQUIRED" ] }, "expectations": { "type": "object", "description": "Summary of expectation rule evaluations against extracted data", "properties": { "errors": { "type": "array", "description": "Unsatisfied required expectations and schema validation failures", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "warnings": { "type": "array", "description": "Unsatisfied recommended expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } }, "info": { "type": "array", "description": "Unsatisfied optional expectations", "items": { "type": "object", "properties": { "nodeType": { "type": "string", "description": "Node type related to this issue (e.g. ark:Transaction)" }, "nodeId": { "type": "string", "description": "Node ID if the issue relates to a specific node" }, "reason": { "type": "string", "description": "Description of the issue" } }, "required": [ "nodeType", "reason" ] } } }, "required": [ "errors", "warnings", "info" ] } }, "required": [ "extraction", "review", "expectations" ] }, "document": { "type": "object", "properties": { "classIdentifier": { "type": "string", "description": "Machine-readable identifier for the document class, or null if classification failed", "example": "property-council-tax-bill", "nullable": true }, "className": { "type": "string", "description": "Human-readable name of the document class", "example": "Property: Council tax bill" }, "classConfidence": { "type": "number", "description": "Confidence score for the document classification (0-100)", "example": 95, "minimum": 0, "maximum": 100 }, "profilesMatched": { "type": "array", "description": "List of extraction profiles that were applied to this document", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the extraction profile", "example": "bill-council-tax-generic" }, "title": { "type": "string", "description": "Human-readable title of the extraction profile", "example": "Generic council tax bill" }, "version": { "type": "string", "description": "Semantic version of the extraction profile", "example": "1.0.0" } } } } }, "required": [ "className", "classConfidence", "profilesMatched" ] }, "text": { "type": "object", "properties": { "source": { "type": "string", "description": "How text was extracted: Embedded (from PDF), OCR (image recognition), or Mixed (combination)", "enum": [ "Embedded", "OCR", "Mixed" ] }, "content": { "type": "string", "description": "Full text content extracted from all pages of the document", "example": "COUNCIL TAX BILL..." } }, "required": [ "source", "content" ] }, "nodes": { "type": "array", "description": "Array of extracted data nodes forming a directed graph. Each node has a `type` property (prefixed with `ark:`) and a unique `id`. Node types include transactions, accounts, addresses, people, etc.", "items": { "type": "object" } } }, "required": [ "status", "document", "text", "nodes" ] }, "links": { "type": "object", "description": "Links for this document extraction", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "requestId", "clientDescription", "inputs" ] } } } }, "400": { "description": "Invalid file type (not PDF/JPEG/PNG), missing document field, or payload exceeds 4.5 MB" }, "500": { "description": "OCR processing failure, document classification error, or extraction pipeline error" } } } }, "/documents/upload": { "post": { "summary": "Create larger file upload", "operationId": "postDocumentsUpload", "description": "\n Creates a new upload target for files larger than the standard 4.5 MB limit,\n supporting synchronous processing of files up to 25 MB (or the client's configured maximum).\n\n Returns an upload ID and an array of pre-signed URIs. The client uploads file\n parts by sending PUT requests with raw bytes to each URI. Only the parts needed\n should be uploaded — the last part may be smaller than partSize.\n\n Once all parts are uploaded, pass the uploadId to POST /documents/single or\n POST /documents/append as a JSON payload to process the file.\n ", "tags": [ "documents" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Pre-signed upload URIs created", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string", "description": "Unique upload identifier returned from POST /documents/upload", "example": "upload_AbCdEfGhIjKlMnO", "pattern": "^upload_[A-Za-z0-9_-]+$" }, "maxBytes": { "type": "integer", "description": "Maximum total file size in bytes", "example": 26214400 }, "partSize": { "type": "integer", "description": "Size of each upload part in bytes (last part may be smaller)", "example": 5242880 }, "parts": { "type": "array", "description": "Array of presigned upload URLs, one per part. Only upload the parts needed for the file size.", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "description": "S3 multipart upload part number", "example": 1, "minimum": 1 }, "uri": { "type": "string", "description": "Pre-signed URI for uploading this part via PUT request. Self-authenticating, no additional headers required.", "example": "https://api.datawollet.com/uploads/upload_AbCdEfGhIjKlMnO/file?X-Amz-Signature=...", "x-format": { "uri": true } }, "byteRange": { "type": "object", "description": "Byte range of the original file that this part covers", "properties": { "start": { "type": "integer", "description": "Start byte offset (inclusive)", "example": 0, "minimum": 0 }, "end": { "type": "integer", "description": "End byte offset (inclusive)", "example": 5242879, "minimum": 0 } }, "required": [ "start", "end" ] } }, "required": [ "partNumber", "uri", "byteRange" ] } } }, "required": [ "uploadId", "maxBytes", "partSize", "parts" ] } } } }, "401": { "description": "Missing or invalid authentication" }, "500": { "description": "Failed to create upload" } } } }, "/graph/fuse": { "post": { "summary": "Create a fused graph from all session sources", "operationId": "postGraphFuse", "description": "\n Creates a consolidated graph by merging all nodes from all sources in the session.\n The fusion process deduplicates nodes and applies graph expressions to derive\n additional relationships and entities.\n\n This is useful for getting a unified view of all extracted data across multiple\n documents in a session.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to create fused graph from" }, "description": "Session ID to create fused graph from", "required": true } ], "tags": [ "graph" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Fused graph created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID this extraction is associated with, or null for standalone requests", "example": "sess_abc123", "nullable": true }, "sourceCount": { "type": "number", "description": "Number of sources that were merged", "example": 3 }, "nodes": { "type": "array", "description": "Array of extracted data nodes forming a directed graph. Each node has a `type` property (prefixed with `ark:`) and a unique `id`. Node types include transactions, accounts, addresses, people, etc.", "items": { "type": "object" } }, "createdAt": { "type": "string", "description": "ISO8601 timestamp when the fused graph was created", "example": "2024-01-15T10:30:00.000Z", "x-format": { "isoDate": true } }, "links": { "type": "object", "description": "Links for this fused graph", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] } }, "required": [ "sessionId", "sourceCount", "nodes", "createdAt" ] } } } }, "400": { "description": "Missing or invalid session-id header, or no sources in session wallet to fuse" }, "403": { "description": "Session key verification failed, missing sessions:read scope, or envelope access requires envelopes:read scope" }, "410": { "description": "Session data is no longer available — encryption key has expired" } } } }, "/oauth/token": { "post": { "summary": "Obtain an access token", "operationId": "postOauthToken", "description": "\n This endpoint is used to obtain access token using client credentials grant only, for machine-to-machine\n (M2M) authentication.\n \n It does not support user-based grants. For user authentication, obtain tokens from one DataWollet's\n user-based Identity Providers (IDPs). Bearer tokens from these IDPs are also accepted by this API.\n \n This endpoint will accept client credentials using three different formats for convenience:\n 1. HTTP Basic Auth: Authorization: Basic base64(client_id:client_secret)\n 2. Form-encoded body: client_id and client_secret in application/x-www-form-urlencoded payload\n 3. JSON body: client_id and client_secret in application/json payload\n ", "parameters": [ { "name": "authorization", "in": "header", "schema": { "type": "string", "description": "HTTP Basic Authentication header (alternative to client_id/client_secret in body)", "pattern": "^Basic .+$" }, "description": "HTTP Basic Authentication header (alternative to client_id/client_secret in body)" } ], "tags": [ "oauth2" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "OAuth2 grant type — only client_credentials is supported", "example": "client_credentials" }, "client_id": { "type": "string", "description": "Client identifier, if not using HTTP Basic Auth", "example": "qzfpenwbykaptwqapn" }, "client_secret": { "type": "string", "description": "Client secret, if not using HTTP Basic Auth", "example": "sk_live_abc123..." }, "scope": { "type": "string", "description": "Space-separated list of requested scopes; omit to receive all allowed scopes", "example": "documents:initiate documents:write" } }, "required": [ "grant_type" ] } }, "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "OAuth2 grant type — only client_credentials is supported", "example": "client_credentials" }, "client_id": { "type": "string", "description": "Client identifier, if not using HTTP Basic Auth", "example": "qzfpenwbykaptwqapn" }, "client_secret": { "type": "string", "description": "Client secret, if not using HTTP Basic Auth", "example": "sk_live_abc123..." }, "scope": { "type": "string", "description": "Space-separated list of requested scopes; omit to receive all allowed scopes", "example": "documents:initiate documents:write" } }, "required": [ "grant_type" ] } } } }, "responses": { "200": { "description": "Access token issued successfully", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "access_token": { "type": "string", "description": "The access token issued by the authorization server", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type": { "type": "string", "description": "The type of the token issued", "enum": [ "Bearer" ] }, "expires_in": { "type": "number", "description": "The lifetime in seconds of the access token", "example": 3600 }, "scope": { "type": "string", "description": "The scope of the access token", "example": "documents:initiate documents:write sessions:write" } }, "required": [ "access_token", "token_type", "expires_in" ] }, { "type": "object", "properties": { "error": { "type": "string", "description": "A single ASCII error code", "example": "invalid_client", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope", "server_error" ] }, "error_description": { "type": "string", "description": "Human-readable ASCII text providing additional information", "example": "Client authentication failed" } }, "required": [ "error" ] } ] } } } }, "400": { "description": "Unsupported grant_type, missing client credentials, or invalid request format" }, "401": { "description": "Client authentication failed — invalid client_id or client_secret" }, "500": { "description": "Internal server error during token signing or scope resolution" } } } }, "/session/events": { "post": { "summary": "Store event data associated with a session", "operationId": "postSessionEvents", "description": "\n Used to store event data associated with a session. This endpoint is used internally by DataWollet as part of its own client libraries to\n record events such as document uploads, extraction status changes, and other relevant actions.\n\n Clients should not use this endpoint directly as the event format and semantics may change without notice, and the data is not made available\n through the standard DataWollet APIs.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID the event are associated with, if not supplied in the payload" }, "description": "Session ID the event are associated with, if not supplied in the payload" } ], "tags": [ "session" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID the events are associated with, if not supplied as a header" }, "events": { "type": "array", "description": "Array of events to store", "items": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Optional event ID, one is generated using the occuredAt otherwise" }, "type": { "type": "string", "description": "Type identifier for the event" }, "occuredAt": { "type": "string", "description": "Timestamp of the event" }, "data": { "type": "object", "description": "Additional data associated with the event" } }, "required": [ "type", "occuredAt" ] } } }, "required": [ "events" ] } } } }, "responses": { "200": { "description": "Events stored successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message that events were stored successfully", "example": "Events stored successfully" } }, "required": [ "message" ] } } } }, "400": { "description": "Missing session ID, empty events array, or invalid credentials" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have the events:write scope" }, "500": { "description": "Failed to store event data in database" } } } }, "/session/resume": { "post": { "summary": "Resume extraction session", "operationId": "postSessionResume", "description": "\n Used to resume or extend an existing session with DataWollet, which otherwise operates exactly like the session start endpoint.\n\n An invalid, expired or non-existent session ID will result in an error response. It is not possible to start a new session\n using this endpoint.\n ", "tags": [ "session" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Existing session ID to resume" }, "sessionTimeout": { "type": "integer", "description": "Session duration in seconds, capped at the maximum allowed duration", "minimum": 1, "maximum": 604800000 }, "sessionPartitionBy": { "type": "string", "description": "Optional partitioning key for session ID generation" }, "clientId": { "type": "string", "description": "Client ID for public client authentication (web SPAs). Requires valid Origin header." } }, "required": [ "sessionId" ] } } } }, "responses": { "200": { "description": "Session resumed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "The ID of the new or resumed session", "example": "sess_a1b2c3d4e5f6" }, "sessionSecret": { "type": "string", "description": "Cryptographically secure secret for client-side session data protection", "example": "kJ9mP2xQ4wR7vB3nL5" }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the session was started", "example": "2024-01-15T10:30:00.000Z" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the session will expire", "example": "2024-01-15T11:30:00.000Z" }, "links": { "type": "object", "description": "Links for this session", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] }, "envelope": { "type": "object", "description": "Envelope details, only where session is associated with an envelope. The client is responsible for storing the envelopeId and envelopeKey securely, to allow sessions to be created at a later date which use the same storage pool. DataWollet does not have access to these on session expiry.", "properties": { "envelopeId": { "type": "string", "description": "The envelope ID", "example": "envelope_abc123def456ghi789jk" }, "envelopeKey": { "type": "string", "description": "Only returned when creating a new envelope", "example": "dGhpcyBpcyBhIGJhc2U2NHVybCBrZXk" } }, "required": [ "envelopeId" ] } }, "required": [ "sessionId", "startedAt", "expiresAt" ] } } } }, "400": { "description": "Session ID not found, expired, or terminated" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Session key verification failed or missing sessions:write scope" }, "500": { "description": "Failed to store resumed session" } } } }, "/session/start": { "post": { "summary": "Start extraction session", "operationId": "postSessionStart", "description": "\n Used to initiate a new session with DataWollet, which can be used to extract data from multiple documents over a period of time prior to its expiry.\n DataWollet does not generally persist data beyond the expiry of a session, and sessions can be explicitly terminated using the appropriate endpoint.\n\n Sessions can be partitioned using a client-supplied key, which ensures that session IDs are unique to that partitioning key. This can be used to\n isolate sessions per end-user or per device, for example. When integrated with a system that has its own sessions, using a partitioning key tied to that\n system's session ID is recommended to prevent session fixation attacks.\n\n If an existing session ID is supplied, the session will be resumed if it is still valid. If the session ID is invalid or expired, a new session will be started.\n\n When a session is continued, the previous requests made within that session are returned in the response, allowing the client to reconstruct the session state.\n\n Session keys are used to protect session data, and are sent to the client as partitioned cookies. These cookies should be stored securely by the client\n and sent with each request that references the session. If the session key is not supplied or is invalid, the session will be treated as invalid and a new\n session will be started.\n\n When using confidential clients, the session key cookie can be used but is not strictly required as sessions are scoped to the client ID. For public clients\n such as web SPAs, the session key cookie is an important security mechanism. Cross-origin use of the session key cookie is made possible using partitioned cookies\n (CHIPS), which allows the cookie to be sent in cross-origin requests while still enforcing same-site restrictions to prevent CSRF attacks. For public clients, a\n valid Origin header is important to identify the correct client configuration.\n\n If authorised with the `envelopes:create` scope, clients can also create an envelope as part of the session creation process, which allows the documents and data\n to be accessed again at a later date by providing the same envelope ID and key. If clients have an existing envelope and the `envelopes:read` scope,\n they can attach that envelope to the session and therefore read (and write if they have the `envelopes:write` scope) the documents and data across multiple \n sessions. The retention period for an envelope is client-specific and is independent of the session expiry - envelopes will remain available until their\n retention period expires, even if all sessions that accessed them have expired.\n\n All sessions have a maximum duration that cannot be exceeded, even if the client requests a longer session timeout. Use envelopes if durable storage is required\n beyond the maximum session duration.\n ", "tags": [ "session" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "nullable": true, "properties": { "sessionId": { "type": "string", "description": "Existing session ID to resume, if any" }, "sessionTimeout": { "type": "integer", "description": "Session duration in seconds, capped at the maximum allowed duration", "minimum": 1, "maximum": 604800000 }, "sessionPartitionBy": { "type": "string", "description": "Optional partitioning key for session ID generation" }, "clientId": { "type": "string", "description": "Client ID for public client authentication (web SPAs). Requires valid Origin header." }, "envelope": { "type": "object", "description": "Envelope configuration for cross-session storage", "properties": { "create": { "type": "boolean", "description": "Create a new envelope for this session", "enum": [ true ] }, "envelopeId": { "type": "string", "description": "Existing envelope ID to attach to", "pattern": "^envelope_[A-Za-z0-9_-]{22}$" }, "envelopeKey": { "type": "string", "description": "Access key for the envelope" }, "ticketId": { "type": "string", "description": "Ticket ID for ticket-based envelope attachment", "pattern": "^ticket_[A-Za-z0-9_-]{22}$" }, "ticketKey": { "type": "string", "description": "Ticket secret for ticket-based envelope attachment" } } } } } } } }, "responses": { "200": { "description": "Session started successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "The ID of the new or resumed session", "example": "sess_a1b2c3d4e5f6" }, "sessionSecret": { "type": "string", "description": "Cryptographically secure secret for client-side session data protection", "example": "kJ9mP2xQ4wR7vB3nL5" }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the session was started", "example": "2024-01-15T10:30:00.000Z" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO8601 timestamp when the session will expire", "example": "2024-01-15T11:30:00.000Z" }, "links": { "type": "object", "description": "Links for this session", "properties": { "self": { "type": "string", "description": "Canonical URI for this resource", "example": "https://api.datawollet.com/session/start", "x-format": { "uri": true } } }, "required": [ "self" ] }, "envelope": { "type": "object", "description": "Envelope details, only where session is associated with an envelope. The client is responsible for storing the envelopeId and envelopeKey securely, to allow sessions to be created at a later date which use the same storage pool. DataWollet does not have access to these on session expiry.", "properties": { "envelopeId": { "type": "string", "description": "The envelope ID", "example": "envelope_abc123def456ghi789jk" }, "envelopeKey": { "type": "string", "description": "Only returned when creating a new envelope", "example": "dGhpcyBpcyBhIGJhc2U2NHVybCBrZXk" } }, "required": [ "envelopeId" ] } }, "required": [ "sessionId", "startedAt", "expiresAt" ] } } } }, "400": { "description": "Invalid payload, envelope operations not supported when resuming, or invalid credentials" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Missing required scope (sessions:write, envelopes:create, or envelopes:read), or envelope access denied" }, "412": { "description": "Envelope not found when attempting to attach" }, "500": { "description": "Failed to generate session ID, create envelope, or store session" } } } }, "/session/websocket": { "post": { "summary": "Create ticket pair for WebSocket", "operationId": "postSessionWebsocket", "description": "\n Creates a connection ticket and authorisation ticket for establishing a WebSocket connection. The connection\n ticket is used by the client to connect to the WebSocket endpoint, while the authorisation ticket is used to\n verify the client's identity once the connection is established. Both tickets are only valid for 30 seconds.\n\n Websockets are used to receive notifications of updates to sessions in near real-time, such as for asynchronous\n document processing or open banking connections. It is not required for typical synchronous document extraction\n operations.\n\n Requires a valid session ID to be supplied as a header. The session must be active and the session key (if \n applicable) must be valid. The request must be authenticated with the 'websockets:initiate' scope.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to create WebSocket ticket for" }, "description": "Session ID to create WebSocket ticket for", "required": true } ], "tags": [ "session" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "200": { "description": "Ticket pair created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionTicket": { "type": "string", "description": "Ticket to use as query parameter when connecting to WebSocket", "x-format": { "guid": true } }, "authorisationTicket": { "type": "string", "description": "Ticket to send in authorise message after connection", "x-format": { "guid": true } }, "expiresIn": { "type": "integer", "description": "Seconds until tickets expire" } }, "required": [ "connectionTicket", "authorisationTicket", "expiresIn" ] } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/session": { "delete": { "summary": "Terminate a session and prevent further disclosure of data", "operationId": "deleteSession", "description": "\n Terminates the specified session, preventing any further access to data associated with that session. The session ID must be supplied as a header because a payload is\n not accepted.\n\n After a session has been terminated, any further attempts to access data associated with that session will be rejected.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID to terminate" }, "description": "Session ID to terminate", "required": true } ], "tags": [ "session" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "204": { "description": "Session terminated successfully" }, "400": { "description": "Session not found, expired, or already terminated" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Session key verification failed or missing sessions:write scope" }, "500": { "description": "Failed to retrieve session information or terminate session" } } } }, "/documents/{requestId}": { "delete": { "summary": "Delete a document from the session", "operationId": "deleteDocumentsRequestid", "description": "\n Removes the specified document request and its associated data from the session. The session ID must be supplied as a header because a payload is\n not accepted.\n\n Clients should ensure that they no longer reference the deleted document in their own session state after a successful deletion.\n ", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string", "description": "Session ID the document belongs to" }, "description": "Session ID the document belongs to", "required": true }, { "name": "requestId", "in": "path", "schema": { "type": "string", "description": "The ID of the request to delete from the session" }, "description": "The ID of the request to delete from the session", "required": true } ], "tags": [ "documents" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "204": { "description": "Document request deleted successfully" }, "400": { "description": "Missing request ID parameter or session ID header" }, "401": { "description": "Missing or invalid API key / bearer token" }, "403": { "description": "Client does not have documents:write scope, session key verification failed, or envelope access requires envelopes:write scope" }, "500": { "description": "Failed to remove document from wallet or database" } } } }, "/envelope/acl/{clientId}": { "delete": { "summary": "Revoke envelope access for a client ID", "operationId": "deleteEnvelopeAclClientid", "description": "Removes the ACL entry for the specified client, preventing future access to the envelope. A client cannot revoke its own access.", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string" }, "required": true }, { "name": "clientId", "in": "path", "schema": { "type": "string" }, "required": true } ], "tags": [ "envelope" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "204": { "description": "Access revoked" }, "403": { "description": "Authentication failed, session key invalid, envelope inactive, no ACL entry for caller, or attempted self-revoke" }, "404": { "description": "No ACL entry found for the specified client on this envelope" }, "409": { "description": "Envelope was modified concurrently — retry the request" }, "412": { "description": "Session is not attached to an envelope" } } } }, "/envelope/acl/{clientId}/{subId}": { "delete": { "summary": "Revoke envelope access for a subject ID", "operationId": "deleteEnvelopeAclClientidSubid", "description": "Removes the ACL entry for the specified client and subject combination. A client cannot revoke its own access.", "parameters": [ { "name": "session-id", "in": "header", "schema": { "type": "string" }, "required": true }, { "name": "clientId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "subId", "in": "path", "schema": { "type": "string" }, "required": true } ], "tags": [ "envelope" ], "security": [ { "API key": [] }, { "Bearer token": [] } ], "responses": { "204": { "description": "Access revoked" }, "403": { "description": "Authentication failed, session key invalid, envelope inactive, no ACL entry for caller, or attempted self-revoke" }, "404": { "description": "No ACL entry found for the specified client and subject on this envelope" }, "409": { "description": "Envelope was modified concurrently — retry the request" }, "412": { "description": "Session is not attached to an envelope" } } } } } }